@surfiran/public-api-client 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# Public API Client
+
+TypeScript types and a fetch-based client for SURFIRAN CRM Public API V1 (`/api/v1/*`). Zero runtime dependencies beyond `fetch`.
+
+## Contract Source
+
+```text
+server/openapi/public-api-v1.yaml  (v0.6.0)
+```
+
+## Current Runtime Scope
+
+Active read endpoints:
+
+```http
+GET /api/v1/homepage
+GET /api/v1/site-navigation
+GET /api/v1/sitemap
+GET /api/v1/search-suggestions
+GET /api/v1/tour-categories
+GET /api/v1/tours
+GET /api/v1/tours/:slug
+GET /api/v1/tours/:slug/departures
+GET /api/v1/tours/:slug/availability
+GET /api/v1/destinations
+GET /api/v1/destinations/:slug
+GET /api/v1/travel-knowledge
+```
+
+Active narrow public write endpoints:
+
+```http
+POST /api/v1/inquiries
+POST /api/v1/booking-intents
+```
+
+Blocked endpoint:
+
+```http
+GET /api/v1/booking-intents/:id
+```
+
+`POST /api/v1/booking-intents` creates a public booking-intent record only. It does not create bookings, traveler records, payments, uploads, inventory holds, supplier-private records, BFF behavior, or Next.js behavior.
+
+`GET /api/v1/booking-intents/:id` remains blocked at `501 PUBLIC_API_ROUTE_NOT_IMPLEMENTED` and is intentionally not exposed by this client.
+
+## Exported Types
+
+All types are aligned with the OpenAPI specification. Key exports:
+
+- `PublicApiErrorCode` - union of current public error code strings
+- `PublicApiV1Path` - union of active client paths
+- `PublicApiV1RouteMap` - maps supported `GET` and `POST` client operations to response types
+- `PublicTourListItem`, `PublicTourDetail`
+- `PublicDepartureListItem`
+- `PublicAvailabilityListItem`, `PublicAvailabilityListResponse`
+- `PublicDestinationListItem`, `PublicDestinationDetail`
+- `PublicTourListResponse`, `PublicTourDetailResponse`
+- `PublicDepartureListResponse`
+- `PublicDestinationListResponse`, `PublicDestinationDetailResponse`
+- `PublicInquiryRequest`, `PublicInquiryResponse`
+- `PublicBookingIntentRequest`, `PublicBookingIntentResponse`
+- `PublicTravelKnowledgeItem`, `PublicTravelKnowledgeResponse`
+- `PublicError`, `PublicErrorEnvelope`
+- `PublicApiNotImplementedError`, `PublicApiValidationError`
+- `PublicApiRateLimitError`, `PublicApiAbuseBlockedError`
+- `PublicApiIdempotencyConflictError`
+
+## Client Functions
+
+```ts
+import { createPublicApiClient } from '@surfiran/public-api-client';
+
+const client = createPublicApiClient({ baseUrl: 'https://crm.example.com' });
+
+const homepage = await client.getPublicHomepage();
+const siteNavigation = await client.getPublicSiteNavigation();
+const sitemap = await client.getPublicSitemap({ type: 'tour' });
+const suggestions = await client.getPublicSearchSuggestions({ q: 'iran' });
+const categories = await client.listPublicTourCategories({ limit: 20 });
+const tours = await client.listPublicTours({ limit: 20 });
+const tour = await client.getPublicTourBySlug('iran-hiking-tour');
+const departures = await client.listPublicTourDepartures('iran-hiking-tour', { limit: 20 });
+const availability = await client.listPublicTourAvailability('iran-hiking-tour', { limit: 20 });
+const destinations = await client.listPublicDestinations({ limit: 20 });
+const destination = await client.getPublicDestinationBySlug('tehran');
+const travelKnowledge = await client.getPublicTravelKnowledge({ type: 'city', q: 'shiraz' });
+```
+
+Public write calls require caller-provided idempotency keys where the Public API contract requires them:
+
+```ts
+const inquiry = await client.createPublicInquiry(
+  { name: 'Traveler', email: 'traveler@example.com', message: 'I am interested in Iran tours.' },
+  'client-generated-idempotency-key',
+);
+
+const bookingIntent = await client.createPublicBookingIntent(
+  { tourSlug: 'iran-hiking-tour', travelerCount: 2 },
+  'client-generated-idempotency-key',
+);
+```
+
+## Boundaries
+
+This package must never:
+
+- Import CRM server modules or connect to MariaDB
+- Call internal CRM routes
+- Export raw CRM row types or sensitive fields
+- Expose `storage_path`, upload-private fields, passenger data, supplier-private data, payment data, audit data, tokens, cookies, or internal notes
+- Add a client method for `GET /api/v1/booking-intents/:id` until that route is separately approved and implemented
+
+## Media Projection Boundary
+
+`heroImage` and `gallery` remain public-safe placeholders until a separate Public API media projection design is approved. This package must not infer public media URLs from `file_uploads.storage_path` or authenticated upload preview URLs.
+
+## Next.js Usage
+
+This client is already consumed from Next.js in production: `apps/web/lib/public*.ts` (tours, destinations, sitemap, search suggestions, site navigation) and multiple `apps/web/components/*` build on `createPublicApiClient` via the `@surfiran/public-api-client` path alias. There is no remaining gate blocking this consumption.
+
+## Next Steps
+
+- Keep this package aligned with `server/openapi/public-api-v1.yaml`
+- Wire code generation only after an owner-approved codegen plan

package/dist/client.d.ts

@@ -0,0 +1,56 @@
+import type { GetPublicSearchSuggestionsParams, GetPublicSitemapParams, GetPublicTravelKnowledgeParams, ListPublicDeparturesParams, ListPublicDestinationsParams, ListPublicTourAccommodationsParams, ListPublicTourAvailabilityParams, ListPublicTourCategoriesParams, ListPublicTourExperiencesParams, ListPublicTravellerStoriesParams, ListPublicTourQuestionsParams, ListPublicTourReviewsParams, ListPublicTourItineraryParams, ListPublicTourRouteParams, ListPublicToursParams, PublicApiResult, PublicAvailabilityListResponse, PublicBookingIntentRequest, PublicBookingIntentResponse, PublicBrochureLeadRequest, PublicBrochureLeadResponse, PublicDepartureListResponse, PublicDestinationDetailResponse, PublicDestinationListResponse, PublicHomepageResponse, PublicInquiryRequest, PublicInquiryResponse, PublicSearchSuggestionsResponse, PublicSitemapResponse, PublicSiteChromeContentResponse, PublicSiteHomeContentResponse, PublicSiteNavigationResponse, PublicSiteTrustPageContentResponse, PublicTourAccommodationListResponse, PublicTourCategoryListResponse, PublicTourDetailResponse, PublicTourExperienceListResponse, PublicTravellerStoryListResponse, PublicTourListResponse, PublicTourQuestionListResponse, PublicTourReviewsSummaryResponse, PublicTourReviewListResponse, PublicTourItineraryResponse, PublicTourRouteResponse, PublicTravelKnowledgeResponse, PublicTravelStatusResponse } from './types.js';
+export type PublicApiClientOptions = {
+    baseUrl: string;
+    fetchImpl?: typeof fetch;
+    requestId?: string;
+    /**
+     * Bounds every request issued by this client. Defaults to 10000ms, matching
+     * the existing AbortController-based timeout precedent in
+     * server/services/webhookDispatcher.ts.
+     */
+    timeoutMs?: number;
+};
+export declare const createPublicApiClient: (options: PublicApiClientOptions) => {
+    listPublicTours(params?: ListPublicToursParams): Promise<PublicApiResult<PublicTourListResponse>>;
+    getPublicTourBySlug(slug: string): Promise<PublicApiResult<PublicTourDetailResponse>>;
+    listPublicTourDepartures(slug: string, params?: ListPublicDeparturesParams): Promise<PublicApiResult<PublicDepartureListResponse>>;
+    listPublicTourQuestions(slug: string, params?: ListPublicTourQuestionsParams): Promise<PublicApiResult<PublicTourQuestionListResponse>>;
+    listPublicTourExperiences(slug: string, params?: ListPublicTourExperiencesParams): Promise<PublicApiResult<PublicTourExperienceListResponse>>;
+    /** Published stories across every tour, plus the tour-less ones — the homepage rail. */
+    listPublicTravellerStories(params?: ListPublicTravellerStoriesParams): Promise<PublicApiResult<PublicTravellerStoryListResponse>>;
+    listPublicTourAccommodations(slug: string, params?: ListPublicTourAccommodationsParams): Promise<PublicApiResult<PublicTourAccommodationListResponse>>;
+    getPublicTourReviewsSummary(slug: string): Promise<PublicApiResult<PublicTourReviewsSummaryResponse>>;
+    listPublicTourReviews(slug: string, params?: ListPublicTourReviewsParams): Promise<PublicApiResult<PublicTourReviewListResponse>>;
+    listPublicTourRoute(slug: string, params?: ListPublicTourRouteParams): Promise<PublicApiResult<PublicTourRouteResponse>>;
+    listPublicTourItinerary(slug: string, params?: ListPublicTourItineraryParams): Promise<PublicApiResult<PublicTourItineraryResponse>>;
+    listPublicTourAvailability(slug: string, params?: ListPublicTourAvailabilityParams): Promise<PublicApiResult<PublicAvailabilityListResponse>>;
+    listPublicDestinations(params?: ListPublicDestinationsParams): Promise<PublicApiResult<PublicDestinationListResponse>>;
+    getPublicDestinationBySlug(slug: string): Promise<PublicApiResult<PublicDestinationDetailResponse>>;
+    createPublicInquiry(body: PublicInquiryRequest, idempotencyKey?: string): Promise<PublicApiResult<PublicInquiryResponse>>;
+    createPublicBookingIntent(body: PublicBookingIntentRequest, idempotencyKey?: string): Promise<PublicApiResult<PublicBookingIntentResponse>>;
+    createPublicBrochureLead(body: PublicBrochureLeadRequest, idempotencyKey?: string): Promise<PublicApiResult<PublicBrochureLeadResponse>>;
+    getPublicHomepage(): Promise<PublicApiResult<PublicHomepageResponse>>;
+    getPublicSiteNavigation(): Promise<PublicApiResult<PublicSiteNavigationResponse>>;
+    getPublicSitemap(params?: GetPublicSitemapParams): Promise<PublicApiResult<PublicSitemapResponse>>;
+    getPublicSearchSuggestions(params: GetPublicSearchSuggestionsParams): Promise<PublicApiResult<PublicSearchSuggestionsResponse>>;
+    listPublicTourCategories(params?: ListPublicTourCategoriesParams): Promise<PublicApiResult<PublicTourCategoryListResponse>>;
+    getPublicTravelStatus(): Promise<PublicApiResult<PublicTravelStatusResponse>>;
+    getPublicSiteContentHome(): Promise<PublicApiResult<PublicSiteHomeContentResponse>>;
+    getPublicSiteContentHeader(): Promise<PublicApiResult<PublicSiteChromeContentResponse>>;
+    getPublicSiteContentFooter(): Promise<PublicApiResult<PublicSiteChromeContentResponse>>;
+    getPublicSiteContentAbout(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentContact(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentFaqs(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentPrivacy(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentTerms(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentResponsibleTravel(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentIranTravelStatus(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentIranVisaInformation(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentMoneyInIran(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentTravelInsurance(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentHealthSafetySupport(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentBookingCancellationPolicy(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentCookiePolicy(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicSiteContentAccessibilityStatement(): Promise<PublicApiResult<PublicSiteTrustPageContentResponse>>;
+    getPublicTravelKnowledge(params: GetPublicTravelKnowledgeParams): Promise<PublicApiResult<PublicTravelKnowledgeResponse>>;
+};

package/dist/client.js

@@ -0,0 +1,288 @@
+const DEFAULT_TIMEOUT_MS = 10000;
+const trimTrailingSlash = (value) => value.replace(/\/+$/, '');
+const isAbortError = (err) => err instanceof Error && err.name === 'AbortError';
+const toTimeoutResult = (status, requestId) => ({
+    ok: false,
+    error: {
+        code: 'PUBLIC_API_CLIENT_TIMEOUT',
+        message: 'Public API request timed out.',
+        status,
+        requestId,
+    },
+    status,
+    requestId,
+});
+const toPublicError = async (response) => {
+    try {
+        const body = await response.json();
+        if (body?.error?.code && body?.error?.message && body?.error?.status)
+            return body;
+    }
+    catch {
+        // Fall through to safe public error below.
+    }
+    return {
+        error: {
+            code: 'PUBLIC_API_CLIENT_ERROR',
+            message: 'Public API request failed.',
+            status: response.status,
+            requestId: response.headers.get('x-request-id'),
+        },
+    };
+};
+const requestJson = async (url, options) => {
+    const fetcher = options.fetchImpl || fetch;
+    const headers = new Headers();
+    if (options.requestId)
+        headers.set('x-request-id', options.requestId);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetcher(url, { headers, signal: controller.signal });
+    }
+    catch (err) {
+        if (isAbortError(err))
+            return toTimeoutResult(0, options.requestId || null);
+        throw err;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+    const requestId = response.headers.get('x-request-id') || options.requestId || null;
+    if (!response.ok) {
+        const publicError = await toPublicError(response);
+        return {
+            ok: false,
+            error: { ...publicError.error, requestId: publicError.error.requestId || requestId },
+            status: response.status,
+            requestId,
+        };
+    }
+    const data = await response.json();
+    return { ok: true, data, status: response.status, requestId };
+};
+const toPaginationQueryString = (params) => {
+    const search = new URLSearchParams();
+    if (params?.limit !== undefined)
+        search.set('limit', String(params.limit));
+    if (params?.cursor)
+        search.set('cursor', params.cursor);
+    const value = search.toString();
+    return value ? `?${value}` : '';
+};
+const toQueryString = (params) => {
+    const search = new URLSearchParams();
+    if (params?.limit !== undefined)
+        search.set('limit', String(params.limit));
+    if (params?.cursor)
+        search.set('cursor', params.cursor);
+    if (params?.destination)
+        search.set('destination', params.destination);
+    if (params?.minDuration !== undefined)
+        search.set('minDuration', String(params.minDuration));
+    if (params?.maxDuration !== undefined)
+        search.set('maxDuration', String(params.maxDuration));
+    const value = search.toString();
+    return value ? `?${value}` : '';
+};
+const toSitemapQueryString = (params) => {
+    const search = new URLSearchParams();
+    if (params?.type)
+        search.set('type', params.type);
+    const value = search.toString();
+    return value ? `?${value}` : '';
+};
+const toSearchSuggestionsQueryString = (params) => {
+    const search = new URLSearchParams();
+    search.set('q', params.q);
+    if (params.limit !== undefined)
+        search.set('limit', String(params.limit));
+    if (params.type)
+        search.set('type', params.type);
+    return `?${search.toString()}`;
+};
+const toTravelKnowledgeQueryString = (params) => {
+    const search = new URLSearchParams();
+    search.set('type', params.type);
+    search.set('q', params.q);
+    if (params.limit !== undefined)
+        search.set('limit', String(params.limit));
+    return `?${search.toString()}`;
+};
+const postJson = async (url, body, options, extraHeaders) => {
+    const fetcher = options.fetchImpl || fetch;
+    const headers = new Headers({ 'Content-Type': 'application/json' });
+    if (options.requestId)
+        headers.set('x-request-id', options.requestId);
+    if (extraHeaders) {
+        for (const [key, value] of Object.entries(extraHeaders)) {
+            headers.set(key, value);
+        }
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetcher(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (isAbortError(err))
+            return toTimeoutResult(0, options.requestId || null);
+        throw err;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+    const requestId = response.headers.get('x-request-id') || options.requestId || null;
+    if (!response.ok) {
+        const publicError = await toPublicError(response);
+        return {
+            ok: false,
+            error: { ...publicError.error, requestId: publicError.error.requestId || requestId },
+            status: response.status,
+            requestId,
+        };
+    }
+    const data = await response.json();
+    return { ok: true, data, status: response.status, requestId };
+};
+export const createPublicApiClient = (options) => {
+    const baseUrl = trimTrailingSlash(options.baseUrl);
+    return {
+        listPublicTours(params) {
+            return requestJson(`${baseUrl}/api/v1/tours${toQueryString(params)}`, options);
+        },
+        getPublicTourBySlug(slug) {
+            return requestJson(`${baseUrl}/api/v1/tours/${encodeURIComponent(slug)}`, options);
+        },
+        listPublicTourDepartures(slug, params) {
+            return requestJson(`${baseUrl}/api/v1/tours/${encodeURIComponent(slug)}/departures${toPaginationQueryString(params)}`, options);
+        },
+        listPublicTourQuestions(slug, params) {
+            return requestJson(`${baseUrl}/api/v1/tours/${encodeURIComponent(slug)}/questions${toPaginationQueryString(params)}`, options);
+        },
+        listPublicTourExperiences(slug, params) {
+            return requestJson(`${baseUrl}/api/v1/tours/${encodeURIComponent(slug)}/experiences${toPaginationQueryString(params)}`, options);
+        },
+        /** Published stories across every tour, plus the tour-less ones — the homepage rail. */
+        listPublicTravellerStories(params) {
+            return requestJson(`${baseUrl}/api/v1/traveller-stories${toPaginationQueryString(params)}`, options);
+        },
+        listPublicTourAccommodations(slug, params) {
+            return requestJson(`${baseUrl}/api/v1/tours/${encodeURIComponent(slug)}/accommodations${toPaginationQueryString(params)}`, options);
+        },
+        getPublicTourReviewsSummary(slug) {
+            return requestJson(`${baseUrl}/api/v1/tours/${encodeURIComponent(slug)}/reviews-summary`, options);
+        },
+        listPublicTourReviews(slug, params) {
+            return requestJson(`${baseUrl}/api/v1/tours/${encodeURIComponent(slug)}/reviews${toPaginationQueryString(params)}`, options);
+        },
+        listPublicTourRoute(slug, params) {
+            return requestJson(`${baseUrl}/api/v1/tours/${encodeURIComponent(slug)}/route${toPaginationQueryString(params)}`, options);
+        },
+        listPublicTourItinerary(slug, params) {
+            return requestJson(`${baseUrl}/api/v1/tours/${encodeURIComponent(slug)}/itinerary${toPaginationQueryString(params)}`, options);
+        },
+        listPublicTourAvailability(slug, params) {
+            return requestJson(`${baseUrl}/api/v1/tours/${encodeURIComponent(slug)}/availability${toPaginationQueryString(params)}`, options);
+        },
+        listPublicDestinations(params) {
+            return requestJson(`${baseUrl}/api/v1/destinations${toPaginationQueryString(params)}`, options);
+        },
+        getPublicDestinationBySlug(slug) {
+            return requestJson(`${baseUrl}/api/v1/destinations/${encodeURIComponent(slug)}`, options);
+        },
+        createPublicInquiry(body, idempotencyKey) {
+            const extra = idempotencyKey ? { 'idempotency-key': idempotencyKey } : undefined;
+            return postJson(`${baseUrl}/api/v1/inquiries`, body, options, extra);
+        },
+        createPublicBookingIntent(body, idempotencyKey) {
+            const extra = idempotencyKey ? { 'idempotency-key': idempotencyKey } : undefined;
+            return postJson(`${baseUrl}/api/v1/booking-intents`, body, options, extra);
+        },
+        createPublicBrochureLead(body, idempotencyKey) {
+            const extra = idempotencyKey ? { 'idempotency-key': idempotencyKey } : undefined;
+            return postJson(`${baseUrl}/api/v1/brochure-leads`, body, options, extra);
+        },
+        getPublicHomepage() {
+            return requestJson(`${baseUrl}/api/v1/homepage`, options);
+        },
+        getPublicSiteNavigation() {
+            return requestJson(`${baseUrl}/api/v1/site-navigation`, options);
+        },
+        getPublicSitemap(params) {
+            return requestJson(`${baseUrl}/api/v1/sitemap${toSitemapQueryString(params)}`, options);
+        },
+        getPublicSearchSuggestions(params) {
+            return requestJson(`${baseUrl}/api/v1/search-suggestions${toSearchSuggestionsQueryString(params)}`, options);
+        },
+        listPublicTourCategories(params) {
+            return requestJson(`${baseUrl}/api/v1/tour-categories${toPaginationQueryString(params)}`, options);
+        },
+        getPublicTravelStatus() {
+            return requestJson(`${baseUrl}/api/v1/travel-status`, options);
+        },
+        // Published CMS site content. One method per approved surface — there is no
+        // key/entity parameter, so a caller cannot request an unapproved CMS entity.
+        getPublicSiteContentHome() {
+            return requestJson(`${baseUrl}/api/v1/site-content/home`, options);
+        },
+        getPublicSiteContentHeader() {
+            return requestJson(`${baseUrl}/api/v1/site-content/header`, options);
+        },
+        getPublicSiteContentFooter() {
+            return requestJson(`${baseUrl}/api/v1/site-content/footer`, options);
+        },
+        getPublicSiteContentAbout() {
+            return requestJson(`${baseUrl}/api/v1/site-content/about`, options);
+        },
+        getPublicSiteContentContact() {
+            return requestJson(`${baseUrl}/api/v1/site-content/contact`, options);
+        },
+        getPublicSiteContentFaqs() {
+            return requestJson(`${baseUrl}/api/v1/site-content/faqs`, options);
+        },
+        getPublicSiteContentPrivacy() {
+            return requestJson(`${baseUrl}/api/v1/site-content/privacy`, options);
+        },
+        getPublicSiteContentTerms() {
+            return requestJson(`${baseUrl}/api/v1/site-content/terms`, options);
+        },
+        getPublicSiteContentResponsibleTravel() {
+            return requestJson(`${baseUrl}/api/v1/site-content/responsible-travel`, options);
+        },
+        getPublicSiteContentIranTravelStatus() {
+            return requestJson(`${baseUrl}/api/v1/site-content/iran-travel-status`, options);
+        },
+        getPublicSiteContentIranVisaInformation() {
+            return requestJson(`${baseUrl}/api/v1/site-content/iran-visa-information`, options);
+        },
+        getPublicSiteContentMoneyInIran() {
+            return requestJson(`${baseUrl}/api/v1/site-content/money-in-iran`, options);
+        },
+        getPublicSiteContentTravelInsurance() {
+            return requestJson(`${baseUrl}/api/v1/site-content/travel-insurance`, options);
+        },
+        getPublicSiteContentHealthSafetySupport() {
+            return requestJson(`${baseUrl}/api/v1/site-content/health-safety-support`, options);
+        },
+        getPublicSiteContentBookingCancellationPolicy() {
+            return requestJson(`${baseUrl}/api/v1/site-content/booking-cancellation-policy`, options);
+        },
+        getPublicSiteContentCookiePolicy() {
+            return requestJson(`${baseUrl}/api/v1/site-content/cookie-policy`, options);
+        },
+        getPublicSiteContentAccessibilityStatement() {
+            return requestJson(`${baseUrl}/api/v1/site-content/accessibility-statement`, options);
+        },
+        getPublicTravelKnowledge(params) {
+            return requestJson(`${baseUrl}/api/v1/travel-knowledge${toTravelKnowledgeQueryString(params)}`, options);
+        },
+    };
+};

package/dist/generated/public-api-v1.d.ts

@@ -0,0 +1,7 @@
+export type GeneratedPublicApiVersion = '0.8.0';
+export type GeneratedPublicApiPath = '/homepage' | '/tours' | '/tours/{slug}' | '/tours/{slug}/availability' | '/tours/{slug}/departures' | '/tours/{slug}/questions' | '/tours/{slug}/experiences' | '/traveller-stories' | '/tours/{slug}/accommodations' | '/tours/{slug}/reviews-summary' | '/tours/{slug}/reviews' | '/tours/{slug}/route' | '/tours/{slug}/itinerary' | '/destinations' | '/destinations/{slug}' | '/sitemap' | '/tour-categories' | '/site-navigation' | '/search-suggestions' | '/travel-status' | '/travel-knowledge' | '/site-content/home' | '/site-content/header' | '/site-content/footer' | '/site-content/about' | '/site-content/contact' | '/site-content/faqs' | '/site-content/privacy' | '/site-content/terms' | '/site-content/responsible-travel' | '/site-content/iran-travel-status' | '/site-content/iran-visa-information' | '/site-content/money-in-iran' | '/site-content/travel-insurance' | '/site-content/health-safety-support' | '/site-content/booking-cancellation-policy' | '/site-content/cookie-policy' | '/site-content/accessibility-statement' | '/inquiries' | '/booking-intents' | '/brochure-leads' | '/booking-intents/{id}';
+export type GeneratedPublicApiOperation = 'GET /homepage' | 'GET /tours' | 'GET /tours/{slug}' | 'GET /tours/{slug}/availability' | 'GET /tours/{slug}/departures' | 'GET /tours/{slug}/questions' | 'GET /tours/{slug}/experiences' | 'GET /traveller-stories' | 'GET /tours/{slug}/accommodations' | 'GET /tours/{slug}/reviews-summary' | 'GET /tours/{slug}/reviews' | 'GET /tours/{slug}/route' | 'GET /tours/{slug}/itinerary' | 'GET /destinations' | 'GET /destinations/{slug}' | 'GET /sitemap' | 'GET /tour-categories' | 'GET /site-navigation' | 'GET /search-suggestions' | 'GET /travel-status' | 'GET /travel-knowledge' | 'GET /site-content/home' | 'GET /site-content/header' | 'GET /site-content/footer' | 'GET /site-content/about' | 'GET /site-content/contact' | 'GET /site-content/faqs' | 'GET /site-content/privacy' | 'GET /site-content/terms' | 'GET /site-content/responsible-travel' | 'GET /site-content/iran-travel-status' | 'GET /site-content/iran-visa-information' | 'GET /site-content/money-in-iran' | 'GET /site-content/travel-insurance' | 'GET /site-content/health-safety-support' | 'GET /site-content/booking-cancellation-policy' | 'GET /site-content/cookie-policy' | 'GET /site-content/accessibility-statement' | 'POST /inquiries' | 'POST /booking-intents' | 'POST /brochure-leads' | 'GET /booking-intents/{id}';
+export type GeneratedPublicApiActiveOperation = 'GET /homepage' | 'GET /tours' | 'GET /tours/{slug}' | 'GET /tours/{slug}/availability' | 'GET /tours/{slug}/departures' | 'GET /tours/{slug}/questions' | 'GET /tours/{slug}/experiences' | 'GET /traveller-stories' | 'GET /tours/{slug}/accommodations' | 'GET /tours/{slug}/reviews-summary' | 'GET /tours/{slug}/reviews' | 'GET /tours/{slug}/route' | 'GET /tours/{slug}/itinerary' | 'GET /destinations' | 'GET /destinations/{slug}' | 'GET /sitemap' | 'GET /tour-categories' | 'GET /site-navigation' | 'GET /search-suggestions' | 'GET /travel-status' | 'GET /travel-knowledge' | 'GET /site-content/home' | 'GET /site-content/header' | 'GET /site-content/footer' | 'GET /site-content/about' | 'GET /site-content/contact' | 'GET /site-content/faqs' | 'GET /site-content/privacy' | 'GET /site-content/terms' | 'GET /site-content/responsible-travel' | 'GET /site-content/iran-travel-status' | 'GET /site-content/iran-visa-information' | 'GET /site-content/money-in-iran' | 'GET /site-content/travel-insurance' | 'GET /site-content/health-safety-support' | 'GET /site-content/booking-cancellation-policy' | 'GET /site-content/cookie-policy' | 'GET /site-content/accessibility-statement' | 'POST /inquiries' | 'POST /booking-intents' | 'POST /brochure-leads';
+export type GeneratedPublicApiBlockedOperation = 'GET /booking-intents/{id}';
+export type GeneratedPublicApiOperationId = 'getPublicHomepage' | 'listPublicTours' | 'getPublicTourBySlug' | 'listPublicTourAvailability' | 'listPublicTourDepartures' | 'listPublicTourQuestions' | 'listPublicTourExperiences' | 'listPublicTravellerStories' | 'listPublicTourAccommodations' | 'getPublicTourReviewsSummary' | 'listPublicTourReviews' | 'listPublicTourRoute' | 'listPublicTourItinerary' | 'listPublicDestinations' | 'getPublicDestinationBySlug' | 'getPublicSitemap' | 'listPublicTourCategories' | 'getPublicSiteNavigation' | 'getPublicSearchSuggestions' | 'getPublicTravelStatus' | 'listPublicTravelKnowledge' | 'getPublicSiteContentHome' | 'getPublicSiteContentHeader' | 'getPublicSiteContentFooter' | 'getPublicSiteContentAbout' | 'getPublicSiteContentContact' | 'getPublicSiteContentFaqs' | 'getPublicSiteContentPrivacy' | 'getPublicSiteContentTerms' | 'getPublicSiteContentResponsibleTravel' | 'getPublicSiteContentIranTravelStatus' | 'getPublicSiteContentIranVisaInformation' | 'getPublicSiteContentMoneyInIran' | 'getPublicSiteContentTravelInsurance' | 'getPublicSiteContentHealthSafetySupport' | 'getPublicSiteContentBookingCancellationPolicy' | 'getPublicSiteContentCookiePolicy' | 'getPublicSiteContentAccessibilityStatement' | 'createPublicInquiry' | 'createPublicBookingIntent' | 'createPublicBrochureLead' | 'getBookingIntent';
+export type GeneratedPublicApiSchemaName = 'PublicHomepageResponse' | 'PublicHomepageStats' | 'PublicHomepageSeo' | 'PublicTourListResponse' | 'PublicTourDetailResponse' | 'PublicAvailabilityListResponse' | 'PublicDepartureListResponse' | 'PublicTourQuestionListResponse' | 'PublicTourExperienceListResponse' | 'PublicTravellerStoryListResponse' | 'PublicTourAccommodationListResponse' | 'PublicTourReviewsSummaryResponse' | 'PublicTourReviewListResponse' | 'PublicTourRouteResponse' | 'PublicDestinationListResponse' | 'PublicDestinationDetailResponse' | 'PublicSitemapResponse' | 'PublicSitemapEntry' | 'PublicTourCategoryListResponse' | 'PublicSearchSuggestionsResponse' | 'PublicTourCategoryListItem' | 'PublicSeo' | 'PublicSearchSuggestion' | 'PublicTourListItem' | 'PublicTourDetail' | 'PublicAvailabilityListItem' | 'PublicDepartureListItem' | 'PublicTourQuestionListItem' | 'PublicTourExperienceFrame' | 'PublicTourExperienceListItem' | 'PublicTravellerStoryListItem' | 'PublicTourAccommodationListItem' | 'PublicTourReviewsAggregate' | 'PublicTourRatingBreakdownItem' | 'PublicTourReviewsSummary' | 'PublicTourReviewListItem' | 'PublicTourRouteStop' | 'PublicTourItineraryDay' | 'PublicTourItineraryResponse' | 'PublicDestinationListItem' | 'PublicDestinationDetail' | 'PublicNavLink' | 'PublicStaticLink' | 'PublicSiteNavigationResponse' | 'PublicSiteRouteKey' | 'PublicSiteCta' | 'PublicSiteHomeSection' | 'PublicSiteHomeContent' | 'PublicSiteHomeContentResponse' | 'PublicSiteNavItem' | 'PublicSiteSocialLink' | 'PublicSiteChromeContent' | 'PublicSiteChromeContentResponse' | 'PublicSiteTrustTitledItem' | 'PublicSiteTrustSection' | 'PublicSiteTrustPageSeo' | 'PublicSiteTrustPageContent' | 'PublicSiteTrustPageContentResponse' | 'CreateInquiryRequest' | 'CreateInquiryResponse' | 'CreateBrochureLeadRequest' | 'CreateBrochureLeadResponse' | 'CreateBookingIntentRequest' | 'PublicBookingIntentStatus' | 'PublicBookingIntentPublicStatus' | 'PublicBookingIntentLinks' | 'CreateBookingIntentSuccessResponse' | 'GetBookingIntentStatusResponse' | 'BookingIntentConflictErrorResponse' | 'BookingIntentResponse' | 'PublicError' | 'PublicApiError' | 'PublicApiNotImplementedError' | 'PublicApiValidationError' | 'PublicApiRateLimitError' | 'PublicApiAbuseBlockedError' | 'PublicApiInternalError' | 'PublicApiNotFoundError' | 'PublicApiTravelStatusUnavailableError' | 'PublicErrorEnvelope' | 'PaginationMeta' | 'PublicTravelStatusState' | 'PublicTravelStatusReviewerLabel' | 'PublicTravelStatusFreshness' | 'PublicOfficialSourceCard' | 'PublicSurfiranOperationalUpdate' | 'PublicTravelStatusCorrectionNotice' | 'PublicTravelStatusHandoff' | 'PublicTravelStatusSection' | 'PublicTravelStatusResponse' | 'PublicTravelKnowledgeItem' | 'PublicTravelKnowledgeResponse';

package/dist/generated/public-api-v1.js

@@ -0,0 +1,4 @@
+// AUTO-GENERATED FILE. DO NOT EDIT.
+// Source: server/openapi/public-api-v1.yaml
+// Generator: scripts/generate-public-api-v1-types.cjs
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createPublicApiClient } from './client.js';
+export type { PublicApiErrorCode, PublicApiV1Path, PublicApiV1RouteMap, PublicError, PublicErrorEnvelope, PublicApiError, PublicApiNotImplementedError, PublicApiValidationError, PublicApiRateLimitError, PublicApiAbuseBlockedError, PublicTourListItem, PublicTourDetail, PublicDepartureListItem, PublicAvailabilityStatus, PublicAvailabilityListItem, PublicAvailabilityListResponse, PublicDestinationListItem, PublicDestinationDetail, PublicTourListResponse, PublicTourDetailResponse, PublicDepartureListResponse, PublicDestinationListResponse, PublicDestinationDetailResponse, PublicApiResult, ListPublicToursParams, ListPublicDeparturesParams, ListPublicTourAvailabilityParams, ListPublicDestinationsParams, PublicInquiryRequest, PublicInquiryResponse, PublicBookingIntentRequest, PublicBookingIntentData, PublicBookingIntentResponse, PublicHomepageStats, PublicHomepageSeo, PublicHomepageResponse, PublicSitemapEntry, PublicSitemapResponse, PublicNavLink, PublicStaticLink, PublicSiteNavigationResponse, PublicTourCategoryListItem, PublicTourCategoryListResponse, PublicSearchSuggestion, PublicSearchSuggestionsResponse, PublicSiteRouteKey, PublicSiteCta, PublicSiteHomeSectionType, PublicSiteHomeSection, PublicSiteHomeContent, PublicSiteHomeContentResponse, PublicSiteNavItem, PublicSiteSocialPlatform, PublicSiteSocialLink, PublicSiteChromeContent, PublicSiteChromeContentResponse, PublicSiteTrustSectionType, PublicSiteTrustTitledItem, PublicSiteTrustParagraphGroup, PublicSiteTrustTitledItemList, PublicSiteTrustBulletList, PublicSiteTrustSection, PublicSiteTrustPageSeo, PublicSiteTrustPageContent, PublicSiteTrustPageContentResponse, PublicTravelStatusState, PublicTravelStatusFreshness, PublicSurfiranOperationalUpdate, PublicTravelStatusResponse, PublicTravelKnowledgeType, PublicTravelKnowledgeItem, PublicTravelKnowledgeResponse, GetPublicSitemapParams, GetPublicSearchSuggestionsParams, GetPublicTravelKnowledgeParams, ListPublicTourCategoriesParams, PublicTravellerStoryListItem, PublicTravellerStoryListResponse, ListPublicTravellerStoriesParams, PublicTourQuestionListItem, PublicTourQuestionListResponse, ListPublicTourQuestionsParams, PublicTourExperienceFrame, PublicTourExperienceListItem, PublicTourExperienceListResponse, ListPublicTourExperiencesParams, PublicTourAccommodationListItem, PublicTourAccommodationListResponse, ListPublicTourAccommodationsParams, PublicTourReviewsAggregate, PublicTourRatingBreakdownItem, PublicTourReviewsSummary, PublicTourReviewsSummaryResponse, PublicTourReviewListItem, PublicTourReviewListResponse, PublicTourReviewsLimit, ListPublicTourReviewsParams, PublicTourRouteStop, PublicTourRouteResponse, ListPublicTourRouteParams, PublicItineraryMealCode, PublicTourItineraryDay, PublicTourItineraryResponse, ListPublicTourItineraryParams, PublicBrochureLeadRequest, PublicBrochureLeadResponse, } from './types.js';
+export type { PublicApiClientOptions } from './client.js';
+export type { GeneratedPublicApiVersion, GeneratedPublicApiPath, GeneratedPublicApiOperation, GeneratedPublicApiActiveOperation, GeneratedPublicApiBlockedOperation, GeneratedPublicApiOperationId, GeneratedPublicApiSchemaName, } from './generated/public-api-v1.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { createPublicApiClient } from './client.js';

package/dist/types.d.ts

@@ -0,0 +1,748 @@
+export type PublicApiErrorCode = 'PUBLIC_API_ROUTE_NOT_IMPLEMENTED' | 'PUBLIC_API_INTERNAL_ERROR' | 'PUBLIC_API_TOUR_NOT_FOUND' | 'PUBLIC_API_DESTINATION_NOT_FOUND' | 'PUBLIC_API_INVALID_QUERY' | 'PUBLIC_API_BOOKING_INTENT_VALIDATION_ERROR' | 'PUBLIC_API_IDEMPOTENCY_CONFLICT' | 'PUBLIC_API_RATE_LIMITED' | 'PUBLIC_API_ABUSE_BLOCKED' | 'PUBLIC_API_TRAVEL_STATUS_UNAVAILABLE' | 'PUBLIC_API_SITE_CONTENT_UNAVAILABLE' | 'PUBLIC_API_CLIENT_TIMEOUT';
+export type PublicApiV1Path = '/homepage' | '/site-navigation' | '/sitemap' | '/search-suggestions' | '/tour-categories' | '/tours' | '/tours/{slug}' | '/tours/{slug}/departures' | '/tours/{slug}/availability' | '/tours/{slug}/reviews' | '/destinations' | '/destinations/{slug}' | '/inquiries' | '/booking-intents' | '/travel-status' | '/travel-knowledge' | '/site-content/home' | '/site-content/header' | '/site-content/footer' | '/site-content/about' | '/site-content/contact' | '/site-content/faqs' | '/site-content/privacy' | '/site-content/terms' | '/site-content/responsible-travel' | '/site-content/iran-travel-status' | '/site-content/iran-visa-information' | '/site-content/money-in-iran' | '/site-content/travel-insurance' | '/site-content/health-safety-support' | '/site-content/booking-cancellation-policy' | '/site-content/cookie-policy' | '/site-content/accessibility-statement';
+export type PublicError = {
+    code: string;
+    message: string;
+    status: number;
+    requestId: string | null;
+};
+export type PublicErrorEnvelope = {
+    error: PublicError;
+};
+export type PublicApiError = {
+    error: PublicError & {
+        code: 'PUBLIC_API_INTERNAL_ERROR' | 'PUBLIC_API_TOUR_NOT_FOUND' | 'PUBLIC_API_DESTINATION_NOT_FOUND';
+    };
+};
+export type PublicApiNotImplementedError = {
+    error: PublicError & {
+        code: 'PUBLIC_API_ROUTE_NOT_IMPLEMENTED';
+        status: 501;
+    };
+};
+export type PublicApiValidationError = {
+    error: PublicError & {
+        code: 'PUBLIC_API_INVALID_QUERY' | 'PUBLIC_API_BOOKING_INTENT_VALIDATION_ERROR';
+        status: 400;
+    };
+};
+export type PublicApiRateLimitError = {
+    error: PublicError & {
+        code: 'PUBLIC_API_RATE_LIMITED';
+        status: 429;
+    };
+};
+export type PublicApiAbuseBlockedError = {
+    error: PublicError & {
+        code: 'PUBLIC_API_ABUSE_BLOCKED';
+        status: 403;
+    };
+};
+export type PublicApiIdempotencyConflictError = {
+    error: PublicError & {
+        code: 'PUBLIC_API_IDEMPOTENCY_CONFLICT';
+        status: 409;
+    };
+};
+export type PublicTourListItem = {
+    id: number;
+    slug: string;
+    title: string;
+    summary: string | null;
+    durationDays: number | null;
+    durationNights: number | null;
+    startingPriceDisplay: string | null;
+    currency: string | null;
+    heroImage: string | null;
+    primaryDestinations: string[];
+    /**
+     * Public trip-theme labels derived from `tour_packages.style` (for example
+     * "Cultural", "Family"). Already served by `GET /api/v1/tours`; declared
+     * optional so a response projected before this field existed still typechecks.
+     * This is a theme, not a product type — see `travelFormat` for group/private.
+     */
+    categoryLabels?: string[];
+    /**
+     * Published activity level (`tour_packages.difficulty`), e.g. "Moderate".
+     * Optional so a response projected before this field existed still typechecks.
+     */
+    activityLevel?: string | null;
+    /**
+     * Countries this tour route touches (`tour_packages.countries`), filtered
+     * server-side to a recognized-country whitelist. Always an array — empty
+     * when the tour is Iran-only or nothing is published yet, never null or
+     * absent, so a consumer never needs a null check before reading `.length`.
+     */
+    countries: string[];
+    /**
+     * True when staff have tagged the tour `beyond-iran` in the CRM — an
+     * explicit editorial claim that the route belongs in the "Iran and beyond"
+     * grid even when its `countries` alone cannot express it (an Iran-only
+     * tribal route, for example). Owner directive 2026-08-07: full Home design
+     * application. Optional so a response projected before this field existed
+     * still typechecks; absent means false.
+     */
+    beyondIran?: boolean;
+    /**
+     * How this route is run — `"Small Group"` or `"Private"` — from
+     * `tour_packages.travel_format` (draft migration
+     * `20260804_tour_packages_travel_format.sql`, not yet executed in
+     * production, so this is `null` for every tour today). Null means not
+     * published, never a guessed default. Optional so a response projected
+     * before this field existed still typechecks. "Tailor-Made" is not a value
+     * here — it has no fixed tour to attach to; it is the `/inquire` flow.
+     */
+    travelFormat?: string | null;
+    /**
+     * Owner directive 2026-08-07 (full Home design application): staff-authored
+     * "was" price display for a current deal
+     * (`tour_packages.previous_price_display`, draft migration
+     * `20260807_tour_packages_deal_pricing_group_size.sql`), e.g.
+     * `"From 2220 EUR"`. Null when no deal is published; never computed from
+     * commercial internals. Optional so a response projected before this field
+     * existed still typechecks.
+     */
+    previousPriceDisplay?: string | null;
+    /**
+     * Staff-authored deal ribbon label (`tour_packages.deal_label`), e.g.
+     * `"−15% off"` or `"Sale"`. Null when no deal is published.
+     */
+    dealLabel?: string | null;
+    /**
+     * Staff-authored savings pill text (`tour_packages.savings_note`), e.g.
+     * `"Save €330 · booked by 31 Aug"`. Null when no deal is published.
+     */
+    savingsNote?: string | null;
+    /**
+     * Published tour-level maximum group size (`tour_packages.max_group_size`),
+     * the "Group / Max N" card fact. A marketing fact, deliberately distinct
+     * from departure-level operational capacity (`tour_departures.max_pax`),
+     * which stays excluded from every public projection. Null when not
+     * published.
+     */
+    maxGroupSize?: number | null;
+    status: string;
+    updatedAt: string | null;
+};
+export type PublicTourDetail = PublicTourListItem & {
+    description: string | null;
+    route: string[];
+    highlights: string[];
+    includedItems: string[];
+    excludedItems: string[];
+    gallery: string[];
+    seoTitle: string | null;
+    seoDescription: string | null;
+};
+export type PublicDepartureListItem = {
+    id: number;
+    tourSlug: string;
+    startDate: string | null;
+    endDate: string | null;
+    availabilityStatus: 'Scheduled' | 'Guaranteed' | 'Sold Out';
+    priceDisplay: string | null;
+    currency: string | null;
+    bookingStatus: string | null;
+};
+export type PublicTourQuestionListItem = {
+    id: number;
+    askerName: string | null;
+    askedAt: string | null;
+    question: string;
+    answer: string;
+    answeredByName: string | null;
+    answeredByRole: string | null;
+    answeredAt: string;
+    /** Computed from (answeredAt - askedAt) at read time. Never a stored value. */
+    answerTimeHours: number;
+};
+export type PublicTourExperienceFrame = {
+    id: number;
+    frameType: 'image' | 'video';
+    /** Null means awaiting footage — render the placeholder, never a stand-in photo. */
+    assetUrl: string | null;
+    posterUrl: string | null;
+    durationMs: number;
+    caption: string | null;
+};
+export type PublicTourExperienceListItem = {
+    id: number;
+    title: string;
+    placeName: string | null;
+    dayNumber: number | null;
+    durationSeconds: number | null;
+    frames: PublicTourExperienceFrame[];
+};
+export type PublicTourAccommodationListItem = {
+    id: number;
+    name: string;
+    cityName: string | null;
+    category: string | null;
+    /** Required contractual substitution wording, e.g. "a similar 4-star". */
+    substitutionLabel: string;
+    descriptionOneLine: string | null;
+    photoUrl: string | null;
+    website: string | null;
+    nightsLabel: string;
+};
+export type PublicTourReviewsAggregate = {
+    /** Null when reviewCount is 0 — never a fabricated or zero rating. */
+    averageRating: number | null;
+    reviewCount: number;
+    source: string | null;
+    /** Most recent staff entry among included reviews — the "as of" honesty marker. */
+    lastVerifiedAt: string | null;
+};
+export type PublicTourRatingBreakdownItem = {
+    dimension: 'guide' | 'itinerary' | 'accommodation' | 'transport' | 'value';
+    score: number;
+    reviewCount: number;
+};
+export type PublicTourReviewsSummary = {
+    aggregate: PublicTourReviewsAggregate;
+    /** Only dimensions a staff member has actually rated appear here. */
+    breakdown: PublicTourRatingBreakdownItem[];
+};
+export type PublicTourReviewListItem = {
+    authorName: string | null;
+    partyType: string | null;
+    reviewDate: string | null;
+    rating: number;
+    title: string;
+    body: string;
+    deepLink: string | null;
+};
+/** Meal codes a day can include. Always returned in B,L,D order. */
+export type PublicItineraryMealCode = 'B' | 'L' | 'D';
+/**
+ * One traveller-facing day of the authored itinerary. Projected from the CRM's
+ * `tour_packages.itinerary` JSON; internal fields (guide notes, transport
+ * notes, per-day media ids, internal identifiers) are never included.
+ *
+ * `title` and `description` are non-nullable because a day lacking either is
+ * omitted from the response rather than returned incomplete — so a consumer
+ * never has to guard against a blank day card.
+ */
+export type PublicTourItineraryDay = {
+    /** Staff-authored day number, and the stable public identifier for the day. */
+    dayNumber: number;
+    title: string;
+    description: string;
+    /** Where guests sleep that night. Null when not authored. */
+    overnightLocation: string | null;
+    /** Traveller-facing route line, e.g. "Tehran → Kashan". */
+    routeSummary: string | null;
+    meals: PublicItineraryMealCode[];
+    /** Staff-typed stay line for the day. Null when not authored. */
+    accommodationNote: string | null;
+    highlights: string[];
+    includedActivities: string[];
+    optionalActivities: string[];
+    landmarks: string[];
+};
+export type PublicTourRouteStop = {
+    id: number;
+    name: string;
+    cityName: string | null;
+    nights: number | null;
+    metaNote: string | null;
+    /** Null means no verified coordinate yet — the stop still renders in the ordered list. */
+    latitude: number | null;
+    longitude: number | null;
+    isStart: boolean;
+    isEnd: boolean;
+};
+export type PublicAvailabilityStatus = 'available' | 'full' | 'unconstrained' | 'not_found' | 'expired' | 'unavailable';
+export type PublicAvailabilityListItem = {
+    tourSlug: string;
+    departureId: number;
+    startDate: string | null;
+    endDate: string | null;
+    availabilityStatus: PublicAvailabilityStatus;
+    availabilityLabel?: string;
+    capacityStatus: PublicAvailabilityStatus;
+    bookingStatus: 'open' | 'closed' | null;
+    currency: string | null;
+    priceDisplay: string | null;
+    promoLabel?: string | null;
+    roomBasis?: 'twin_share' | 'double_share' | 'single_room' | 'triple_share' | 'family_room' | null;
+    remainingCapacityBucket: 'available' | 'limited' | 'full' | 'unconstrained' | 'unknown';
+    /**
+     * Owner directive 2026-08-07: full Home design application — limited-state
+     * remaining places (1–4) are published; raw capacity stays private.
+     * Present ONLY when remainingCapacityBucket === 'limited'.
+     */
+    remainingPlaces?: number;
+    holdable: boolean;
+    publicUrl?: string;
+    ctaUrl?: string;
+    updatedAt: string | null;
+};
+export type PublicDestinationListItem = {
+    id: number;
+    slug: string;
+    name: string;
+    summary: string | null;
+    heroImage: string | null;
+    updatedAt: string | null;
+};
+export type PublicDestinationDetail = PublicDestinationListItem & {
+    description: string | null;
+    seoTitle: string | null;
+    seoDescription: string | null;
+};
+export type PublicTourListResponse = {
+    data: PublicTourListItem[];
+    nextCursor: string | null;
+    total: number;
+};
+export type PublicTourDetailResponse = {
+    data: PublicTourDetail;
+};
+export type PublicDepartureListResponse = {
+    data: PublicDepartureListItem[];
+    nextCursor: string | null;
+    total: number;
+};
+export type PublicTourQuestionListResponse = {
+    data: PublicTourQuestionListItem[];
+    total: number;
+};
+export type PublicTourExperienceListResponse = {
+    data: PublicTourExperienceListItem[];
+    total: number;
+};
+export type PublicTravellerStoryListItem = PublicTourExperienceListItem & {
+    /**
+     * Public slug of the story's tour. Null when the story belongs to no tour, or
+     * when its tour is not public — the rail renders the story unlinked rather
+     * than linking to a page that would 404.
+     */
+    tourSlug: string | null;
+};
+export type PublicTravellerStoryListResponse = {
+    data: PublicTravellerStoryListItem[];
+    total: number;
+};
+export type PublicTourAccommodationListResponse = {
+    data: PublicTourAccommodationListItem[];
+    total: number;
+};
+export type PublicTourReviewsSummaryResponse = {
+    data: PublicTourReviewsSummary;
+};
+export type PublicTourReviewListResponse = {
+    data: PublicTourReviewListItem[];
+    total: number;
+};
+export type PublicTourRouteResponse = {
+    data: PublicTourRouteStop[];
+    total: number;
+};
+/** Empty `data` means the tour has no publishable itinerary content. */
+export type PublicTourItineraryResponse = {
+    data: PublicTourItineraryDay[];
+    total: number;
+};
+export type PublicAvailabilityListResponse = {
+    data: PublicAvailabilityListItem[];
+    nextCursor: string | null;
+    total: number;
+};
+export type PublicDestinationListResponse = {
+    data: PublicDestinationListItem[];
+    nextCursor: string | null;
+    total: number;
+};
+export type PublicDestinationDetailResponse = {
+    data: PublicDestinationDetail;
+};
+export type PublicInquiryRequest = {
+    name: string;
+    email: string;
+    message: string;
+    tourSlug?: string | null;
+    /**
+     * Optional requested departure date (YYYY-MM-DD) when the inquiry was
+     * submitted from a specific public departure card. No departure identifier or
+     * commercial data is sent.
+     */
+    departureDate?: string | null;
+};
+export type PublicInquiryResponse = {
+    data: {
+        accepted: boolean;
+        inquiryId: string;
+    };
+};
+export type PublicBookingIntentRequest = {
+    tourSlug: string;
+    departureId?: number | null;
+    travelerCount: number;
+    leadTravelerName?: string | null;
+    leadTravelerEmail?: string | null;
+    leadTravelerPhone?: string | null;
+    notes?: string | null;
+};
+export type PublicBookingIntentStatus = 'received' | 'needs_review' | 'expired' | 'cancelled' | 'converted_internal';
+export type PublicBookingIntentData = {
+    publicId: string;
+    status: PublicBookingIntentStatus;
+    tourSlug: string;
+    departureId: number | null;
+    travelerCount: number;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt: string | null;
+    priceAtCapture: {
+        amount: number;
+        currency: string;
+    } | null;
+};
+export type PublicBookingIntentResponse = {
+    data: PublicBookingIntentData;
+};
+export type PublicBrochureLeadRequest = {
+    email: string;
+    tourSlug: string;
+    /** Separate GDPR double opt-in for the newsletter only, never implied by the brochure request itself. */
+    newsletterConsent?: boolean;
+    sourceUrl?: string | null;
+    utmSource?: string | null;
+    utmMedium?: string | null;
+    utmCampaign?: string | null;
+};
+export type PublicBrochureLeadResponse = {
+    data: {
+        accepted: boolean;
+        leadId: string;
+    };
+};
+export type PublicHomepageStats = {
+    publishedTours: number;
+    publishedDestinations: number;
+};
+export type PublicHomepageSeo = {
+    title: string;
+    description: string;
+};
+export type PublicHomepageResponse = {
+    data: {
+        featuredTours: PublicTourListItem[];
+        popularDestinations: PublicDestinationListItem[];
+        stats: PublicHomepageStats;
+        seo: PublicHomepageSeo;
+    };
+};
+export type PublicSitemapEntry = {
+    path: string;
+    type: 'tour' | 'destination';
+    slug: string;
+    lastModified: string | null;
+    priority: number;
+    changeFrequency: 'weekly' | 'monthly';
+};
+export type PublicSitemapResponse = {
+    data: PublicSitemapEntry[];
+    total: number;
+};
+export type PublicNavLink = {
+    slug: string;
+    label: string;
+};
+export type PublicStaticLink = {
+    key: string;
+    label: string;
+    href: string;
+};
+export type PublicSiteNavigationResponse = {
+    primaryDestinations: PublicNavLink[];
+    featuredTourLinks: PublicNavLink[];
+    staticLinks: PublicStaticLink[];
+    footerLinks: PublicStaticLink[];
+};
+export type PublicTourCategoryListItem = {
+    id: number;
+    slug: string;
+    name: string;
+    tourCount: number;
+};
+export type PublicTourCategoryListResponse = {
+    data: PublicTourCategoryListItem[];
+    nextCursor: string | null;
+    total: number;
+};
+export type PublicSearchSuggestion = {
+    type: 'tour' | 'destination';
+    label: string;
+    slug: string;
+    path: string;
+};
+export type PublicSearchSuggestionsResponse = {
+    data: PublicSearchSuggestion[];
+    total: number;
+    query: string;
+};
+export type PublicTravelKnowledgeType = 'city' | 'landmark' | 'activity' | 'accommodation_label' | 'theme';
+export type PublicTravelKnowledgeItem = {
+    type: PublicTravelKnowledgeType;
+    slug: string;
+    canonicalName: string;
+    publicSafeSummary?: string | null;
+    category?: string | null;
+    city?: string | null;
+    region?: string | null;
+    country?: string | null;
+};
+export type PublicTravelKnowledgeResponse = {
+    data: PublicTravelKnowledgeItem[];
+    meta: {
+        type: PublicTravelKnowledgeType;
+        count: number;
+        truncated: boolean;
+    };
+};
+export type PublicTravelStatusState = 'current' | 'review_due_soon' | 'stale' | 'source_unavailable' | 'conflicting_official_sources' | 'retired_source' | 'emergency_correction_active';
+export type PublicTravelStatusReviewerLabel = 'Travel advisory review team' | 'Visa and entry review team' | 'Travel practicalities review team' | 'SURFIRAN operations team' | 'SURFIRAN';
+export type PublicTravelStatusFreshness = {
+    reviewedAt: string | null;
+    nextReviewBy: string | null;
+    reviewedByRole: PublicTravelStatusReviewerLabel;
+};
+export type PublicOfficialSourceCard = {
+    sourceKey: string;
+    sourceCategory: 'official-travel-advice' | 'official-visa-entry' | 'regulated-practical-constraint';
+    sourceName: string;
+    issuingOrganization: string;
+    jurisdiction: string;
+    canonicalUrl: string;
+    applicability: string;
+    summary: string | null;
+    freshness: PublicTravelStatusFreshness;
+};
+export type PublicSurfiranOperationalUpdate = {
+    summary: string | null;
+    unavailable: boolean;
+    freshness: PublicTravelStatusFreshness | null;
+};
+export type PublicTravelStatusCorrectionNotice = {
+    message: string;
+    correctedAt: string;
+};
+export type PublicTravelStatusHandoff = {
+    route: '/inquire';
+    message: string;
+};
+export type PublicTravelStatusSection = {
+    scope: 'advisory' | 'visa' | 'border' | 'payment' | 'insurance' | 'aviation' | 'communications';
+    state: PublicTravelStatusState;
+    officialSources: PublicOfficialSourceCard[];
+    conflictDisclosure: string | null;
+};
+export type PublicTravelStatusResponse = {
+    data: {
+        overallState: PublicTravelStatusState;
+        sections: PublicTravelStatusSection[];
+        surfiranOperationalUpdate: PublicSurfiranOperationalUpdate;
+        correctionNotice: PublicTravelStatusCorrectionNotice | null;
+        handoff: PublicTravelStatusHandoff;
+        freshness: PublicTravelStatusFreshness;
+    };
+};
+/** Closed public route vocabulary. Routing is resolved by the rendering layer. */
+export type PublicSiteRouteKey = 'home' | 'tours' | 'tour-categories' | 'destinations' | 'about' | 'contact' | 'inquire' | 'faqs' | 'privacy' | 'terms' | 'responsible-travel' | 'iran-travel-status' | 'iran-visa-information' | 'money-in-iran' | 'travel-insurance' | 'health-safety-support' | 'booking-cancellation-policy' | 'cookie-policy' | 'accessibility-statement';
+export type PublicSiteCta = {
+    label: string;
+    routeKey: PublicSiteRouteKey;
+};
+export type PublicSiteHomeSectionType = 'feature' | 'tour_highlight' | 'destination_highlight';
+export type PublicSiteHomeSection = {
+    type: PublicSiteHomeSectionType;
+    heading: string | null;
+    summary: string | null;
+};
+export type PublicSiteHomeContent = {
+    pageTitle: string;
+    heroHeading: string;
+    heroIntroduction: string;
+    cta: PublicSiteCta | null;
+    sections: PublicSiteHomeSection[];
+};
+export type PublicSiteHomeContentResponse = {
+    data: PublicSiteHomeContent | null;
+};
+export type PublicSiteNavItem = {
+    label: string;
+    routeKey: PublicSiteRouteKey;
+};
+export type PublicSiteSocialPlatform = 'facebook' | 'instagram' | 'twitter' | 'linkedin' | 'youtube' | 'tiktok';
+export type PublicSiteSocialLink = {
+    platform: PublicSiteSocialPlatform;
+    url: string;
+};
+export type PublicSiteChromeContent = {
+    navItems: PublicSiteNavItem[];
+    cta: PublicSiteCta | null;
+    contactEmail: string | null;
+    contactPhone: string | null;
+    socialLinks: PublicSiteSocialLink[];
+};
+export type PublicSiteChromeContentResponse = {
+    data: PublicSiteChromeContent | null;
+};
+/** Closed discriminator over the three plain-text About/Contact section shapes. */
+export type PublicSiteTrustSectionType = 'paragraph_group' | 'titled_item_list' | 'bullet_list';
+export type PublicSiteTrustTitledItem = {
+    title: string;
+    body: string;
+};
+export type PublicSiteTrustParagraphGroup = {
+    type: 'paragraph_group';
+    title: string;
+    paragraphs: string[];
+};
+export type PublicSiteTrustTitledItemList = {
+    type: 'titled_item_list';
+    title: string;
+    intro: string | null;
+    items: PublicSiteTrustTitledItem[];
+};
+export type PublicSiteTrustBulletList = {
+    type: 'bullet_list';
+    title: string;
+    bullets: string[];
+};
+export type PublicSiteTrustSection = PublicSiteTrustParagraphGroup | PublicSiteTrustTitledItemList | PublicSiteTrustBulletList;
+export type PublicSiteTrustPageSeo = {
+    title: string | null;
+    description: string | null;
+    ogTitle: string | null;
+    ogDescription: string | null;
+    robotsIndex: boolean;
+    robotsFollow: boolean;
+};
+/**
+ * Published About or Contact page content. Page copy only — the public inquiry
+ * form stays entirely application-owned and is never described or configured
+ * by this contract.
+ */
+export type PublicSiteTrustPageContent = {
+    eyebrow: string;
+    pageHeading: string;
+    pageIntro: string;
+    cta: PublicSiteCta | null;
+    sections: PublicSiteTrustSection[];
+    seo: PublicSiteTrustPageSeo;
+};
+export type PublicSiteTrustPageContentResponse = {
+    data: PublicSiteTrustPageContent | null;
+};
+export type PublicApiV1RouteMap = {
+    'GET /homepage': PublicHomepageResponse;
+    'GET /site-navigation': PublicSiteNavigationResponse;
+    'GET /sitemap': PublicSitemapResponse;
+    'GET /search-suggestions': PublicSearchSuggestionsResponse;
+    'GET /tour-categories': PublicTourCategoryListResponse;
+    'GET /tours': PublicTourListResponse;
+    'GET /tours/{slug}': PublicTourDetailResponse;
+    'GET /tours/{slug}/departures': PublicDepartureListResponse;
+    'GET /tours/{slug}/availability': PublicAvailabilityListResponse;
+    'GET /tours/{slug}/reviews': PublicTourReviewListResponse;
+    'GET /destinations': PublicDestinationListResponse;
+    'GET /destinations/{slug}': PublicDestinationDetailResponse;
+    'POST /inquiries': PublicInquiryResponse;
+    'POST /booking-intents': PublicBookingIntentResponse;
+    'POST /brochure-leads': PublicBrochureLeadResponse;
+    'GET /travel-status': PublicTravelStatusResponse;
+    'GET /travel-knowledge': PublicTravelKnowledgeResponse;
+    'GET /site-content/home': PublicSiteHomeContentResponse;
+    'GET /site-content/header': PublicSiteChromeContentResponse;
+    'GET /site-content/footer': PublicSiteChromeContentResponse;
+    'GET /site-content/about': PublicSiteTrustPageContentResponse;
+    'GET /site-content/contact': PublicSiteTrustPageContentResponse;
+    'GET /site-content/faqs': PublicSiteTrustPageContentResponse;
+    'GET /site-content/privacy': PublicSiteTrustPageContentResponse;
+    'GET /site-content/terms': PublicSiteTrustPageContentResponse;
+    'GET /site-content/responsible-travel': PublicSiteTrustPageContentResponse;
+    'GET /site-content/iran-travel-status': PublicSiteTrustPageContentResponse;
+    'GET /site-content/iran-visa-information': PublicSiteTrustPageContentResponse;
+    'GET /site-content/money-in-iran': PublicSiteTrustPageContentResponse;
+    'GET /site-content/travel-insurance': PublicSiteTrustPageContentResponse;
+    'GET /site-content/health-safety-support': PublicSiteTrustPageContentResponse;
+    'GET /site-content/booking-cancellation-policy': PublicSiteTrustPageContentResponse;
+    'GET /site-content/cookie-policy': PublicSiteTrustPageContentResponse;
+    'GET /site-content/accessibility-statement': PublicSiteTrustPageContentResponse;
+};
+export type PublicApiResult<T> = {
+    ok: true;
+    data: T;
+    status: number;
+    requestId: string | null;
+} | {
+    ok: false;
+    error: PublicError;
+    status: number;
+    requestId: string | null;
+};
+export type ListPublicToursParams = {
+    limit?: number;
+    cursor?: string;
+    /** Itinerary-derived destination slug, matched server-side. */
+    destination?: string;
+    /** Inclusive lower bound on `durationDays`. */
+    minDuration?: number;
+    /** Inclusive upper bound on `durationDays`. */
+    maxDuration?: number;
+};
+export type ListPublicDeparturesParams = {
+    limit?: number;
+    cursor?: string;
+};
+export type ListPublicTourQuestionsParams = {
+    limit?: number;
+};
+export type ListPublicTourExperiencesParams = {
+    limit?: number;
+};
+export type ListPublicTravellerStoriesParams = {
+    limit?: number;
+};
+export type ListPublicTourAccommodationsParams = {
+    limit?: number;
+};
+export type PublicTourReviewsLimit = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+export type ListPublicTourReviewsParams = {
+    /** Maximum review cards to return. Defaults to 3 when omitted; accepted range is 1 through 12. */
+    limit?: PublicTourReviewsLimit;
+};
+export type ListPublicTourRouteParams = {
+    limit?: number;
+};
+export type ListPublicTourItineraryParams = {
+    limit?: number;
+};
+export type ListPublicDestinationsParams = {
+    limit?: number;
+    cursor?: string;
+};
+export type GetPublicSitemapParams = {
+    type?: 'tour' | 'destination';
+};
+export type GetPublicSearchSuggestionsParams = {
+    q: string;
+    limit?: number;
+    type?: 'tour' | 'destination';
+};
+export type ListPublicTourCategoriesParams = {
+    limit?: number;
+    cursor?: string;
+};
+export type ListPublicTourAvailabilityParams = {
+    limit?: number;
+    cursor?: string;
+};
+export type GetPublicTravelKnowledgeParams = {
+    type: PublicTravelKnowledgeType;
+    q: string;
+    limit?: number;
+};

package/dist/types.js

@@ -0,0 +1,3 @@
+// TypeScript interfaces aligned with server/openapi/public-api-v1.yaml v0.8.0
+// Zero runtime code. Types only.
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@surfiran/public-api-client",
+  "version": "0.1.0",
+  "description": "TypeScript types and client for SURFIRAN CRM Public API V1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./generated": {
+      "types": "./dist/generated/public-api-v1.d.ts",
+      "import": "./dist/generated/public-api-v1.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "generate": "node ../../scripts/generate-public-api-v1-types.cjs",
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "prepack": "npm run typecheck && npm test && npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "verify:generated": "npm run generate && git diff --exit-code -- src/generated/public-api-v1.ts"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.2.2",
+    "vitest": "^4.1.8"
+  }
+}