@surfiran/public-api-client 0.37.0 → 0.38.0

package/README.md

@@ -22,7 +22,16 @@ The package version, contract version, source commit, and API release identity o
 
 New client versions must consume the exact immutable GitHub Release assets produced from a successful `SURFIRAN/surfiran-crm-api` main-branch CI run. The release tag is `public-api-contract/<source SHA>-<run ID>-<attempt>` and contains only `public-api-v1.yaml` and `manifest.json`. Publication verifies the immutable release and both GitHub release attestations, the tag SHA, final successful source run, asset digests, manifest identity, and checked-in snapshot bytes. If any check is unavailable, publication stops. Pull-request artifacts are verification evidence only and are not valid release inputs. This repository must never read another repository's private working tree at build time.
 
-`src/generated/public-api-v1.ts` is generated from the checked-in snapshot; `src/client.ts` and `src/types.ts` are maintained in this repository against that reviewed contract. Never hand-edit generated source.
+### Generated and hand-written source
+
+`npm run generate` produces two files from the checked-in snapshot. Never hand-edit either.
+
+- `src/generated/public-api-v1.ts` (`scripts/generate-public-api-v1.cjs`): the contract version and the path, operation, operation ID and schema name unions. Published under the `./generated` export.
+- `src/generated/public-api-v1.schema.ts` (`scripts/generate-public-api-v1-schema.cjs`, exact-pinned `openapi-typescript` devDependency): the full contract `paths`, `components` and `operations` types. Verification input only; it is excluded from the build and not published.
+
+`src/client.ts` and `src/types.ts` stay hand-written against that reviewed contract, and they are what the package exports. `test/types-conformance.ts` checks every hand-written type whose name matches a contract schema against `components['schemas'][Name]` field by field: missing and extra fields, required/optional, and field types. It also checks that every `PublicApiV1RouteMap` route is in `PublicApiV1Path` and in the contract. `npm run typecheck` runs it through `tsconfig.conformance.json`, and `test/types-conformance-coverage.test.ts` (run by `npm test`) keeps its list of checked names exact.
+
+Known deviations are listed in that file's `Allowlist`, one entry per field with its kind and reason. Kept-required fields (contract optional), kept-optional fields (contract required), branded localisation IDs and the contract-debt field `PublicTourListItem.travelFormat` are listed there. An entry that stops deviating fails the check, so the fix and the entry's removal land together. `npm run verify:generated` fails when either generated file is stale.
 
 ## Boundary
 
@@ -69,8 +78,8 @@ A new contract update must:
 2. make a reviewed package version change before rewriting contract provenance;
 3. verify/download the release assets, then run `sync:api-contract-artifact` with the exact API commit, run ID, and run attempt;
 4. update `contract/public-api-v1.yaml` and `contract/provenance.json` together;
-5. regenerate the client;
-6. pass artifact verification, package verification, reproducibility, tests, typecheck, and build;
+5. regenerate the client (`npm run generate` writes both generated files);
+6. pass artifact verification, package verification, reproducibility, tests, typecheck (including the type conformance check, adding new contract fields to `src/types.ts` or allowlisting a reviewed deviation), and build;
 7. use a reviewed compatible or breaking version decision before publication.
 
 The sync command rejects rewriting provenance for the current package version and rejects API artifacts that are not valid release inputs.
@@ -83,7 +92,7 @@ Do not duplicate the endpoint list here; the pinned OpenAPI snapshot and generat
 
 ## Publication and rollback
 
-Routine package CI uses the owned non-production `owned-ci-linux` / `owned-ci-heavy` runner pool with the Node.js version pinned by [ci.yml](.github/workflows/ci.yml). CodeQL Default Setup independently selects `owned-ci-linux` in repository code-scanning settings; its TypeScript extractor requires Node.js 20 or newer on the runner service's standard PATH, even when ordinary CI uses `setup-node`. Follow the [GitHub Actions budget policy effective 2026-10-13](https://github.com/SURFIRAN/surfiran-crm-api/blob/main/docs/architecture/REPOSITORY_BOUNDARIES.md#github-actions-budget-policy-owner-override-2026-10-13): GitHub Actions must use owned runners, with no GitHub-hosted or paid fallback. The separate [Codex Cloud development preference](https://github.com/SURFIRAN/surfiran-crm-api/blob/main/docs/architecture/REPOSITORY_BOUNDARIES.md#execution-resources-owner-policy-2026-10-05) remains unchanged. Manual publication uses the dedicated trusted `package-publish` runner and never occupies `surfdmc-prod-deploy`; package and cross-repository artifact credentials do not move to Home or general CI workers.
+Routine package CI runs `Verify Public API client` on a standard GitHub-hosted `ubuntu-24.04` runner with the Node.js version pinned by [ci.yml](.github/workflows/ci.yml). It is light and secretless, refuses to run unless the runner reports `github-hosted` Linux X64, and is bounded by a 5-minute timeout. CodeQL Default Setup independently selects `owned-ci-linux` in repository code-scanning settings; its TypeScript extractor requires Node.js 20 or newer on the runner service's standard PATH, even when ordinary CI uses `setup-node`. Approved providers, quotas and limits are owned by [Ordinary CI providers](https://github.com/SURFIRAN/surfiran-crm-api/blob/main/docs/architecture/REPOSITORY_BOUNDARIES.md#ordinary-ci-providers-owner-decision-2026-11-01); paid capacity needs new owner approval. Manual publication uses the dedicated trusted `package-publish` runner and never occupies `surfdmc-prod-deploy`; package and cross-repository artifact credentials do not move to Home or general CI workers.
 
 Publication is manual and repository-local through [public-api-client-publish.yml](.github/workflows/public-api-client-publish.yml). It runs on `main` only with explicit publication authorization and `publish_confirm=PUBLISH`. A future version must be bound to an exact reviewed API contract release, pass package/reproducibility checks and publication preflight, create release provenance, and provide an exact previous rollback version. The workflow uses `PUBLIC_API_CONTRACT_READ_TOKEN` to read the private immutable API release and a separate `PUBLIC_API_CLIENT_RELEASE_SETTINGS_READ_TOKEN` with scoped Administration:read to confirm immutable Releases are enabled for this client repository. Before publishing to npmjs.org, it creates or exactly reuses an immutable client release `public-api-client/v<package version>` containing the packed tarball and provenance JSON. It marks the evidence release as non-latest and verifies its asset digests, source tag SHA, and GitHub release attestations. Retries must reproduce the same bytes, including the explicit generation timestamp. Missing or unverifiable release or publication evidence blocks npm publication; the workflow does not use Actions artifact storage for these gates.
 

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

@@ -1,4 +1,4 @@
-export type GeneratedPublicApiVersion = '0.29.0';
+export type GeneratedPublicApiVersion = '0.30.1';
 export type GeneratedPublicApiPath = '/booking-intents' | '/booking-intents/{id}' | '/bot-protection' | '/brochure-leads' | '/destinations' | '/destinations/{slug}' | '/homepage' | '/inquiries' | '/locales' | '/localization/previews/{candidateId}' | '/localization/releases/{releaseId}' | '/localization/ui-catalogs/{snapshotId}' | '/marketing-unsubscribes' | '/newsletter/confirm' | '/newsletter/subscriptions' | '/reviews' | '/search' | '/search-suggestions' | '/site-content/about' | '/site-content/accessibility-statement' | '/site-content/booking-cancellation-policy' | '/site-content/contact' | '/site-content/cookie-policy' | '/site-content/destination-iran' | '/site-content/destinations/{country}' | '/site-content/faqs' | '/site-content/footer' | '/site-content/header' | '/site-content/health-safety-support' | '/site-content/home' | '/site-content/iran-travel-status' | '/site-content/iran-visa-information' | '/site-content/money-in-iran' | '/site-content/privacy' | '/site-content/responsible-travel' | '/site-content/tailor-made' | '/site-content/terms' | '/site-content/travel-insurance' | '/site-features' | '/site-navigation' | '/sitemap' | '/support-requests' | '/tour-categories' | '/tours' | '/tours/{slug}' | '/tours/{slug}/accommodations' | '/tours/{slug}/availability' | '/tours/{slug}/departures' | '/tours/{slug}/experiences' | '/tours/{slug}/itinerary' | '/tours/{slug}/page' | '/tours/{slug}/preview' | '/tours/{slug}/preview/page' | '/tours/{slug}/questions' | '/tours/{slug}/reviews' | '/tours/{slug}/reviews-summary' | '/tours/{slug}/route' | '/travel-insurance/rates' | '/travel-knowledge' | '/travel-status' | '/traveller-stories';
 export type GeneratedPublicApiOperation = 'GET /booking-intents/{id}' | 'GET /bot-protection' | 'GET /destinations' | 'GET /destinations/{slug}' | 'GET /homepage' | 'GET /locales' | 'GET /localization/previews/{candidateId}' | 'GET /localization/releases/{releaseId}' | 'GET /localization/ui-catalogs/{snapshotId}' | 'GET /marketing-unsubscribes' | 'GET /newsletter/confirm' | 'GET /reviews' | 'GET /search' | 'GET /search-suggestions' | 'GET /site-content/about' | 'GET /site-content/accessibility-statement' | 'GET /site-content/booking-cancellation-policy' | 'GET /site-content/contact' | 'GET /site-content/cookie-policy' | 'GET /site-content/destination-iran' | 'GET /site-content/destinations/{country}' | 'GET /site-content/faqs' | 'GET /site-content/footer' | 'GET /site-content/header' | 'GET /site-content/health-safety-support' | 'GET /site-content/home' | 'GET /site-content/iran-travel-status' | 'GET /site-content/iran-visa-information' | 'GET /site-content/money-in-iran' | 'GET /site-content/privacy' | 'GET /site-content/responsible-travel' | 'GET /site-content/tailor-made' | 'GET /site-content/terms' | 'GET /site-content/travel-insurance' | 'GET /site-features' | 'GET /site-navigation' | 'GET /sitemap' | 'GET /tour-categories' | 'GET /tours' | 'GET /tours/{slug}' | 'GET /tours/{slug}/accommodations' | 'GET /tours/{slug}/availability' | 'GET /tours/{slug}/departures' | 'GET /tours/{slug}/experiences' | 'GET /tours/{slug}/itinerary' | 'GET /tours/{slug}/page' | 'GET /tours/{slug}/preview' | 'GET /tours/{slug}/preview/page' | 'GET /tours/{slug}/questions' | 'GET /tours/{slug}/reviews' | 'GET /tours/{slug}/reviews-summary' | 'GET /tours/{slug}/route' | 'GET /travel-insurance/rates' | 'GET /travel-knowledge' | 'GET /travel-status' | 'GET /traveller-stories' | 'POST /booking-intents' | 'POST /brochure-leads' | 'POST /inquiries' | 'POST /marketing-unsubscribes' | 'POST /newsletter/subscriptions' | 'POST /support-requests';
 export type GeneratedPublicApiActiveOperation = 'GET /bot-protection' | 'GET /destinations' | 'GET /destinations/{slug}' | 'GET /homepage' | 'GET /locales' | 'GET /localization/previews/{candidateId}' | 'GET /localization/releases/{releaseId}' | 'GET /localization/ui-catalogs/{snapshotId}' | 'GET /marketing-unsubscribes' | 'GET /newsletter/confirm' | 'GET /reviews' | 'GET /search' | 'GET /search-suggestions' | 'GET /site-content/about' | 'GET /site-content/accessibility-statement' | 'GET /site-content/booking-cancellation-policy' | 'GET /site-content/contact' | 'GET /site-content/cookie-policy' | 'GET /site-content/destination-iran' | 'GET /site-content/destinations/{country}' | 'GET /site-content/faqs' | 'GET /site-content/footer' | 'GET /site-content/header' | 'GET /site-content/health-safety-support' | 'GET /site-content/home' | 'GET /site-content/iran-travel-status' | 'GET /site-content/iran-visa-information' | 'GET /site-content/money-in-iran' | 'GET /site-content/privacy' | 'GET /site-content/responsible-travel' | 'GET /site-content/tailor-made' | 'GET /site-content/terms' | 'GET /site-content/travel-insurance' | 'GET /site-features' | 'GET /site-navigation' | 'GET /sitemap' | 'GET /tour-categories' | 'GET /tours' | 'GET /tours/{slug}' | 'GET /tours/{slug}/accommodations' | 'GET /tours/{slug}/availability' | 'GET /tours/{slug}/departures' | 'GET /tours/{slug}/experiences' | 'GET /tours/{slug}/itinerary' | 'GET /tours/{slug}/page' | 'GET /tours/{slug}/preview' | 'GET /tours/{slug}/preview/page' | 'GET /tours/{slug}/questions' | 'GET /tours/{slug}/reviews' | 'GET /tours/{slug}/reviews-summary' | 'GET /tours/{slug}/route' | 'GET /travel-insurance/rates' | 'GET /travel-knowledge' | 'GET /travel-status' | 'GET /traveller-stories' | 'POST /booking-intents' | 'POST /brochure-leads' | 'POST /inquiries' | 'POST /marketing-unsubscribes' | 'POST /newsletter/subscriptions' | 'POST /support-requests';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { createPublicApiClient } from './client.js';
-export type { PublicApiErrorCode, PublicApiV1Path, PublicApiV1RouteMap, PublicError, PublicErrorEnvelope, PublicApiError, PublicApiNotImplementedError, PublicApiValidationError, PublicApiRateLimitError, PublicApiAbuseBlockedError, PublicTourListItem, PublicTourRegion, PublicTourDetail, PublicTourDetailEditorial, PublicDepartureListItem, PublicAvailabilityStatus, PublicAvailabilityListItem, PublicAvailabilityListResponse, PublicDestinationListItem, PublicCityDestinationContent, PublicCityExperience, PublicCityImage, PublicCityLabelledValue, PublicCityLink, PublicCityNextPlace, PublicCityReason, PublicCityResource, PublicCityStayLink, PublicDestinationDetail, PublicTourListResponse, PublicTourCatalogMetadata, PublicTourCatalogFacetKey, PublicTourCatalogFacetOption, PublicTourCatalogSort, PublicTourCatalogStartingFrom, PublicTourCatalogDepartureSummary, PublicTourDetailResponse, PublicAvailabilityState, PublicTourPageFormat, PublicTourPagePrivateOption, PublicTourPageLeg, PublicTourPageMeal, PublicTourPageKnowSlot, PublicTourPageBadgeTone, PublicTourPageFactKey, PublicTourPageFactIcon, PublicTourPageGalleryKey, PublicTourPageRoomOptionId, PublicTourPageImage, PublicTourPageKeyValue, PublicTourPageBadge, PublicTourPageOpenGraphImage, PublicTourPageByline, PublicTourPageChecked, PublicTourPagePrivateOverride, PublicTourPageFact, PublicTourPageHero, PublicTourPageVideo, PublicTourPageQuote, PublicTourPageGalleryGroup, PublicTourPageExperienceFrame, PublicTourPageExperience, PublicTourPageMap, PublicTourPageStop, PublicTourPageItineraryDay, PublicTourPagePlace, PublicTourPageStay, PublicTourPageTitledBody, PublicTourPageDeparturesEmpty, PublicTourPageMonth, PublicTourPageRoomOption, PublicTourPageRoomPriceByCurrency, PublicTourPageDeparture, PublicTourPagePriceFrom, PublicTourPageReviewSubRating, PublicTourPageReviewReply, PublicTourPageReviewItem, PublicTourPageReviews, PublicTourPageQuestion, PublicTourPageKnowExtra, PublicTourPageCredibility, PublicTourPageOperator, PublicTourPageTailorBand, PublicTourPageBrochure, PublicTourPageRelatedCard, PublicTourPage, PublicTourPageResponse, PublicDepartureListResponse, PublicDestinationListResponse, PublicDestinationDetailResponse, PublicApiResult, ListPublicToursParams, GetPublicTourParams, GetPublicDestinationParams, PublicContentLocale, GetPublicTourPreviewParams, ListPublicDeparturesParams, ListPublicTourAvailabilityParams, ListPublicDestinationsParams, PublicInquiryRequest, PublicTourTailorJourney, PublicInquiryResponse, PublicSupportRequestCategory, PublicSupportRequest, PublicSupportRequestRecaptcha, PublicSupportRequestResponse, PublicMarketingUnsubscribeRequest, PublicMarketingUnsubscribeResponse, PublicNewsletterSubscriptionSource, PublicNewsletterSubscriptionLocale, PublicNewsletterSubscriptionRequest, PublicNewsletterSubscriptionResponse, PublicNewsletterSubscriptionOptions, PublicBookingIntentRequest, PublicBookingIntentData, PublicBookingIntentResponse, PublicHomepageStats, PublicHomepageSeo, PublicHomepageResponse, PublicSitemapEntry, PublicSitemapResponse, PublicNavLink, PublicStaticLink, PublicSiteNavigationResponse, PublicTourCategoryListItem, PublicTourCategoryListResponse, PublicPriceDisplayByCurrency, PublicSearchResultItem, PublicSearchResultGroup, PublicSearchResultsResponse, PublicSearchSuggestion, PublicSearchSuggestionsResponse, PublicSiteRouteKey, PublicSiteCta, PublicSiteHomeSectionType, PublicSiteHomeSection, PublicSiteHomeContent, PublicSiteHomeContentResponse, PublicSiteNavItem, PublicSiteSocialPlatform, PublicSiteSocialLink, PublicSiteHeaderOffice, PublicSiteHeaderMenuCategory, PublicSiteHeaderMenuEditorial, PublicSiteHeaderQuickLink, PublicSiteHeaderSearchShortcuts, PublicSiteFooterNavGroupLink, PublicSiteFooterNavGroup, PublicSiteFooterSupportBand, PublicSiteFooterPaymentNote, PublicSiteChromeContent, PublicSiteChromeContentResponse, PublicSiteFeatureStates, PublicSiteFeaturesResponse, PublicBotCheckErrorCode, PublicBotProtectionRecaptcha, PublicBotProtectionResponse, PublicTravelInsuranceAgeBand, PublicTravelInsuranceDurationBand, PublicTravelInsuranceRates, PublicTravelInsuranceRatesResponse, LocaleTag, LocalizationReleaseId, UiCatalogSnapshotId, CmsContentSnapshotId, PublicLocaleRegistryItem, PublicLocaleRegistryResponse, PublicLocalizationRelease, PublicLocalizationReleaseResponse, PublicUiCatalogMessage, PublicUiCatalog, PublicUiCatalogResponse, PublicSiteTrustSectionType, PublicSiteTrustTitledItem, PublicSiteTrustParagraphGroup, PublicSiteTrustTitledItemList, PublicSiteTrustBulletList, PublicSiteTrustSection, PublicSiteTrustPageSeo, PublicSiteTrustPageContent, PublicSiteTrustPageContentResponse, PublicSiteBlock, PublicSiteBlockPageContent, PublicSiteBlockPageContentResponse, PublicTravelStatusState, PublicTravelStatusFreshness, PublicSurfiranOperationalUpdate, PublicTravelStatusResponse, PublicTravelKnowledgeType, PublicTravelKnowledgeItem, PublicTravelKnowledgeResponse, GetPublicSitemapParams, GetPublicSearchResultsParams, GetPublicSearchSuggestionsParams, GetPublicTravelKnowledgeParams, ListPublicTourCategoriesParams, PublicTravellerStoryListItem, PublicTravellerStoryListResponse, ListPublicTravellerStoriesParams, PublicTourQuestionListItem, PublicTourQuestionListResponse, ListPublicTourQuestionsParams, PublicTourExperienceFrame, PublicTourExperienceListItem, PublicTourExperienceListResponse, ListPublicTourExperiencesParams, PublicTourAccommodationListItem, PublicTourAccommodationListResponse, ListPublicTourAccommodationsParams, PublicTourReviewsAggregate, PublicTourRatingBreakdownItem, PublicTourReviewsSummary, PublicTourReviewsSummaryResponse, PublicTourReviewListItem, PublicTourReviewListResponse, PublicSiteReviewListResponse, ListPublicSiteReviewsParams, PublicTourReviewsLimit, ListPublicTourReviewsParams, PublicTourRouteStop, PublicRouteTransportMode, PublicTourRouteResponse, ListPublicTourRouteParams, PublicItineraryMealCode, PublicTourItineraryDay, PublicTourItineraryResponse, ListPublicTourItineraryParams, PublicBrochureLeadRequest, PublicBrochureLeadResponse, } from './types.js';
+export type { PublicApiErrorCode, PublicApiV1Path, PublicApiV1RouteMap, PublicError, PublicErrorEnvelope, PublicApiError, PublicApiNotImplementedError, PublicApiValidationError, PublicApiRateLimitError, PublicApiAbuseBlockedError, PublicTourListItem, PublicTourRegion, PublicTourDetail, PublicTourDetailEditorial, PublicTourMediaItem, PublicDepartureListItem, PublicAvailabilityStatus, PublicAvailabilityListItem, PublicAvailabilityListResponse, PublicDestinationListItem, PublicCityDestinationContent, PublicCityExperience, PublicCityImage, PublicCityLabelledValue, PublicCityLink, PublicCityNextPlace, PublicCityReason, PublicCityResource, PublicCityStayLink, PublicDestinationDetail, PublicTourListResponse, PublicTourCatalogMetadata, PublicTourCatalogFacetKey, PublicTourCatalogFacetOption, PublicTourCatalogSort, PublicTourCatalogStartingFrom, PublicTourCatalogDepartureSummary, PublicTourDetailResponse, PublicAvailabilityState, PublicTourPageFormat, PublicTourPagePrivateOption, PublicTourPageLeg, PublicTourPageMeal, PublicTourPageKnowSlot, PublicTourPageBadgeTone, PublicTourPageFactKey, PublicTourPageFactIcon, PublicTourPageGalleryKey, PublicTourPageRoomOptionId, PublicTourPageImage, PublicTourPageKeyValue, PublicTourPageBadge, PublicTourPageOpenGraphImage, PublicTourPageByline, PublicTourPageChecked, PublicTourPagePrivateOverride, PublicTourPageFact, PublicTourPageHero, PublicTourPageVideo, PublicTourPageQuote, PublicTourPageGalleryGroup, PublicTourPageExperienceFrame, PublicTourPageExperience, PublicTourPageMap, PublicTourPageStop, PublicTourPageItineraryDay, PublicTourPagePlace, PublicTourPageStay, PublicTourPageTitledBody, PublicTourPageDeparturesEmpty, PublicTourPageMonth, PublicTourPageRoomOption, PublicTourPageRoomPriceByCurrency, PublicTourPageDeparture, PublicTourPagePriceFrom, PublicTourPageReviewSubRating, PublicTourPageReviewReply, PublicTourPageReviewItem, PublicTourPageReviews, PublicTourPageQuestion, PublicTourPageKnowExtra, PublicTourPageCredibility, PublicTourPageOperator, PublicTourPageTailorBand, PublicTourPageBrochure, PublicTourPageRelatedCard, PublicTourPage, PublicTourPageResponse, PublicDepartureListResponse, PublicDestinationListResponse, PublicDestinationDetailResponse, PublicApiResult, ListPublicToursParams, GetPublicTourParams, GetPublicDestinationParams, PublicContentLocale, GetPublicTourPreviewParams, ListPublicDeparturesParams, ListPublicTourAvailabilityParams, ListPublicDestinationsParams, PublicInquiryRequest, PublicTourTailorJourney, PublicInquiryResponse, PublicSupportRequestCategory, PublicSupportRequest, PublicSupportRequestRecaptcha, PublicSupportRequestResponse, PublicMarketingUnsubscribeRequest, PublicMarketingUnsubscribeResponse, PublicNewsletterSubscriptionSource, PublicNewsletterSubscriptionLocale, PublicNewsletterSubscriptionRequest, PublicNewsletterSubscriptionResponse, PublicNewsletterSubscriptionOptions, PublicBookingIntentRequest, PublicBookingIntentData, PublicBookingIntentResponse, PublicHomepageStats, PublicHomepageSeo, PublicHomepageResponse, PublicSitemapEntry, PublicSitemapResponse, PublicNavLink, PublicStaticLink, PublicSiteNavigationResponse, PublicTourCategoryListItem, PublicTourCategoryListResponse, PublicPriceDisplayByCurrency, PublicSearchResultItem, PublicSearchResultGroup, PublicSearchResultsResponse, PublicSearchSuggestion, PublicSearchSuggestionsResponse, PublicSiteRouteKey, PublicSiteCta, PublicSiteHomeSectionType, PublicSiteHomeSection, PublicSiteHomeContent, PublicSiteHomeContentResponse, PublicSiteNavItem, PublicSiteSocialPlatform, PublicSiteSocialLink, PublicSiteHeaderOffice, PublicSiteHeaderMenuCategory, PublicSiteHeaderMenuEditorial, PublicSiteHeaderQuickLink, PublicSiteHeaderSearchShortcuts, PublicSiteFooterNavGroupLink, PublicSiteFooterNavGroup, PublicSiteFooterSupportBand, PublicSiteFooterPaymentNote, PublicSiteChromeContent, PublicSiteChromeContentResponse, PublicSiteFeatureStates, PublicSiteFeaturesResponse, PublicBotCheckErrorCode, PublicBotProtectionRecaptcha, PublicBotProtectionResponse, PublicTravelInsuranceAgeBand, PublicTravelInsuranceDurationBand, PublicTravelInsuranceRates, PublicTravelInsuranceRatesResponse, LocaleTag, LocalizationReleaseId, UiCatalogSnapshotId, CmsContentSnapshotId, PublicLocaleRegistryItem, PublicLocaleRegistryResponse, PublicLocalizationRelease, PublicLocalizationReleaseResponse, PublicUiCatalogMessage, PublicUiCatalog, PublicUiCatalogResponse, PublicSiteTrustSectionType, PublicSiteTrustTitledItem, PublicSiteTrustParagraphGroup, PublicSiteTrustTitledItemList, PublicSiteTrustBulletList, PublicSiteTrustSection, PublicSiteTrustPageSeo, PublicSiteTrustPageContent, PublicSiteTrustPageContentResponse, PublicSiteBlock, PublicSiteBlockPageContent, PublicSiteBlockPageContentResponse, PublicTravelStatusState, PublicTravelStatusFreshness, PublicSurfiranOperationalUpdate, PublicTravelStatusResponse, PublicTravelKnowledgeType, PublicTravelKnowledgeItem, PublicTravelKnowledgeResponse, GetPublicSitemapParams, GetPublicSearchResultsParams, GetPublicSearchSuggestionsParams, GetPublicTravelKnowledgeParams, ListPublicTourCategoriesParams, PublicTravellerStoryListItem, PublicTravellerStoryListResponse, ListPublicTravellerStoriesParams, PublicTourQuestionListItem, PublicTourQuestionListResponse, ListPublicTourQuestionsParams, PublicTourExperienceFrame, PublicTourExperienceListItem, PublicTourExperienceListResponse, ListPublicTourExperiencesParams, PublicTourAccommodationListItem, PublicTourAccommodationListResponse, ListPublicTourAccommodationsParams, PublicTourReviewsAggregate, PublicTourRatingBreakdownItem, PublicTourReviewsSummary, PublicTourReviewsSummaryResponse, PublicTourReviewListItem, PublicTourReviewListResponse, PublicSiteReviewListResponse, ListPublicSiteReviewsParams, PublicTourReviewsLimit, ListPublicTourReviewsParams, PublicTourRouteStop, PublicRouteTransportMode, 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/types.d.ts

@@ -1,10 +1,10 @@
 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_LOCALIZATION_NOT_FOUND' | 'PUBLIC_API_LOCALIZATION_UNAVAILABLE' | 'PUBLIC_API_CLIENT_TIMEOUT';
-export type PublicApiV1Path = '/homepage' | '/site-navigation' | '/site-features' | '/locales' | '/localization/previews/{candidateId}' | '/localization/releases/{releaseId}' | '/localization/ui-catalogs/{snapshotId}' | '/sitemap' | '/search-suggestions' | '/tour-categories' | '/tours' | '/tours/{slug}' | '/tours/{slug}/preview' | '/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/tailor-made' | '/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' | '/site-content/destination-iran';
+export type PublicApiV1Path = '/homepage' | '/site-navigation' | '/site-features' | '/bot-protection' | '/travel-insurance/rates' | '/locales' | '/localization/previews/{candidateId}' | '/localization/releases/{releaseId}' | '/localization/ui-catalogs/{snapshotId}' | '/sitemap' | '/search' | '/search-suggestions' | '/tour-categories' | '/tours' | '/tours/{slug}' | '/tours/{slug}/preview' | '/tours/{slug}/page' | '/tours/{slug}/preview/page' | '/tours/{slug}/departures' | '/tours/{slug}/availability' | '/tours/{slug}/reviews' | '/destinations' | '/destinations/{slug}' | '/inquiries' | '/support-requests' | '/marketing-unsubscribes' | '/newsletter/subscriptions' | '/booking-intents' | '/brochure-leads' | '/travel-status' | '/travel-knowledge' | '/site-content/home' | '/site-content/header' | '/site-content/footer' | '/site-content/about' | '/site-content/contact' | '/site-content/tailor-made' | '/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' | '/site-content/destination-iran';
 export type PublicError = {
     code: string;
     message: string;
     status: number;
-    requestId: string | null;
+    requestId?: string | null;
     /**
      * Optional public-safe diagnostic object (contract schema PublicError.details).
      * Shape varies by error code — e.g. the destination-not-found error may
@@ -78,10 +78,24 @@ export type PublicTourListItem = {
     id: number;
     slug: string;
     title: string;
-    summary: string | null;
+    summary?: string | null;
+    /** Card excerpt. Optional: older responses omit it. */
+    excerpt?: string | null;
     durationDays: number | null;
     durationNights: number | null;
+    /** Finished duration label. Optional: older responses omit it. */
+    durationDisplay?: string | null;
+    /**
+     * Published fixed starting price only. Null when this tour has no fixed
+     * public price; Private tours may instead carry `priceOnRequestLabel`.
+     */
     startingPriceDisplay: string | null;
+    /**
+     * Owner-approved controlled on-request price label for a Private tour with
+     * no fixed public price. Never a raw pricing row, amount, commercial
+     * calculation, or internal note. Optional: older responses omit it.
+     */
+    priceOnRequestLabel?: string | null;
     currency: string | null;
     /**
      * The same published starting price rendered in each display currency the
@@ -92,9 +106,13 @@ export type PublicTourListItem = {
      * A currency with no active rate for this price's own currency is `null`, and
      * the consumer falls back to `startingPriceDisplay` as published.
      */
-    priceDisplayByCurrency: PublicPriceDisplayByCurrency;
+    priceDisplayByCurrency?: PublicPriceDisplayByCurrency;
     heroImage: string | null;
+    /** Public hero image URL. Optional: older responses omit it. */
+    heroImageUrl?: string | null;
     primaryDestinations: string[];
+    /** Display label for the tour's destinations. Optional: older responses omit it. */
+    destinationLabel?: string | null;
     /**
      * Public trip-theme labels derived from `tour_packages.style` (for example
      * "Cultural", "Family"). Already served by `GET /api/v1/tours`; declared
@@ -185,18 +203,41 @@ export type PublicTourListItem = {
      * provenance and null semantics as `startCity`.
      */
     finishCity?: string | null;
+    /**
+     * The same verified external review aggregate GET /tours/{slug}/reviews-summary
+     * publishes for this tour, from the same projection, so a catalogue card and
+     * the tour page never disagree. Null when the tour has no visible source
+     * aggregate and no visible review rows: render nothing rather than a zero
+     * rating or an invented count. Optional: older responses omit it.
+     */
+    reviewAggregate?: PublicTourReviewsAggregate | null;
+    /** Canonical public page URL. Optional: older responses omit it. */
+    publicUrl?: string;
+    /** Call-to-action URL. Optional: older responses omit it. */
+    ctaUrl?: string;
     status: string;
-    updatedAt: string | null;
+    updatedAt?: string | null;
+    /**
+     * Public-safe SEO projection. The contract requires it; optional here so
+     * consumers stay compatible with servers predating the seo projection, as on
+     * PublicDestinationListItem.
+     */
+    seo?: PublicSeo;
 };
 export type PublicTourDetail = PublicTourListItem & {
-    description: string | null;
+    description?: string | null;
     route: string[];
-    highlights: string[];
-    includedItems: string[];
-    excludedItems: string[];
+    highlights?: string[];
+    includedItems?: string[];
+    excludedItems?: string[];
     gallery: string[];
-    seoTitle: string | null;
-    seoDescription: string | null;
+    /**
+     * Published tour photographs with authored alt text, grouping and focal
+     * point. Optional: older responses omit it.
+     */
+    media?: PublicTourMediaItem[];
+    seoTitle?: string | null;
+    seoDescription?: string | null;
     editorial?: PublicTourDetailEditorial | null;
     /**
      * Operator-configured "Tailor This Journey" call to action.
@@ -214,6 +255,34 @@ export type PublicTourDetail = PublicTourListItem & {
     /** Operator-curated related tours (PR-13 / OA-9), in the pinned order. Empty when none are pinned/published. */
     relatedJourneys?: PublicTourListItem[];
 };
+/** One published tour photograph (contract schema PublicTourMediaItem). */
+export type PublicTourMediaItem = {
+    url: string;
+    /**
+     * Alternative text authored against this asset. An empty string marks a
+     * decorative photograph, a deliberate published state, not missing data.
+     */
+    alt: string;
+    /** Operator-authored caption, or null when none. */
+    caption: string | null;
+    /**
+     * Gallery tab this photograph belongs under. Null means ungrouped: it appears
+     * under All photos only and never invents a tab of its own.
+     */
+    group: 'route' | 'people' | 'activities' | 'stay' | 'transport' | null;
+    /**
+     * 0-1 pair a renderer turns into object-position. Null means no focal point
+     * was authored; a null axis means centre on that axis.
+     */
+    focalPoint: {
+        x: number | null;
+        y: number | null;
+    } | null;
+    /** True for the tour listing photograph. Exactly one per tour. */
+    isLead: boolean;
+    /** The operator's own ordering position within this tour's media. */
+    order: number;
+};
 export type PublicTourTailorJourney = {
     enabled: boolean;
     /** Canonical public slug of the source tour, for inquiry attribution. Present only when enabled. */
@@ -225,24 +294,29 @@ export type PublicTourTailorJourney = {
     /** Published customisation prompts, in the operator's authored order. */
     suggestedCustomizationOptions?: string[];
 };
+/**
+ * Operator-authored tour page editorial. Every field and sub-field is optional,
+ * as in the contract (client 0.38.0 aligned them): render nothing for an absent
+ * value rather than assume the projection sent it.
+ */
 export type PublicTourDetailEditorial = {
-    tourType: string | null;
-    tourCode: string | null;
-    breadcrumbTitle: string | null;
-    authorName: string | null;
-    authorUrl: string | null;
-    authorRole: string | null;
-    lastReviewedAt: string | null;
-    guideLabel: string | null;
-    groupSizeNote: string | null;
-    paceLabel: string | null;
-    paceNote: string | null;
-    comfortLabel: string | null;
-    comfortNote: string | null;
-    guideNote: string | null;
-    startLabel: string | null;
-    endLabel: string | null;
-    startEndNote: string | null;
+    tourType?: string | null;
+    tourCode?: string | null;
+    breadcrumbTitle?: string | null;
+    authorName?: string | null;
+    authorUrl?: string | null;
+    authorRole?: string | null;
+    lastReviewedAt?: string | null;
+    guideLabel?: string | null;
+    groupSizeNote?: string | null;
+    paceLabel?: string | null;
+    paceNote?: string | null;
+    comfortLabel?: string | null;
+    comfortNote?: string | null;
+    guideNote?: string | null;
+    startLabel?: string | null;
+    endLabel?: string | null;
+    startEndNote?: string | null;
     /** Operator-authored prose above the route map; null when none is stored (contract 0.23.0). */
     routeIntro?: string | null;
     /** Note under the included / not included lists; null when none is stored (contract 0.23.0). */
@@ -254,45 +328,65 @@ export type PublicTourDetailEditorial = {
     arrivesByAir?: boolean;
     /** As arrivesByAir, for leaving by air from the last stop (contract 0.26.0). */
     departsByAir?: boolean;
-    overviewParagraphs: string[];
-    heroAltText: string | null;
-    heroObjectPosition: string | null;
-    galleryAltTexts: string[];
-    galleryObjectPositions: string[];
-    heroVideo: {
-        url: string;
-        posterUrl: string | null;
-        durationLabel: string | null;
+    /**
+     * Private-version product state: `exact` = the published itinerary can run
+     * privately as shown, `similar` = only a similar private journey designed
+     * from it, `none` = scheduled group departures only. Absent or null means no
+     * state is published and a consumer renders no private call to action. Never
+     * carries a price; a private trip is always priced on request.
+     */
+    privateOption?: PublicTourPagePrivateOption | null;
+    /**
+     * The visa benefit this tour sells. Absent, null or mode `pending` means
+     * nothing is published and a consumer renders no visa line. Never carries a
+     * processing time, an eligibility promise, or an approval claim.
+     */
+    visa?: {
+        mode: 'included' | 'advice' | 'optional' | 'pending';
+        /** Whether the Iranian authorisation code is included. Null when the tour does not state it. */
+        authCodeIncluded?: boolean | null;
+        /** The separately payable government or consular fee, in the tour's own published words. */
+        feeNote?: string | null;
+    } | null;
+    overviewParagraphs?: string[];
+    heroAltText?: string | null;
+    heroObjectPosition?: string | null;
+    galleryAltTexts?: string[];
+    galleryObjectPositions?: string[];
+    heroVideo?: {
+        url?: string;
+        posterUrl?: string | null;
+        durationLabel?: string | null;
     } | null;
-    heroQuote: {
-        text: string;
-        authorName: string | null;
-        travelDate: string | null;
-        sourceUrl: string | null;
+    heroQuote?: {
+        text?: string;
+        authorName?: string | null;
+        travelDate?: string | null;
+        sourceUrl?: string | null;
     } | null;
     payment?: {
-        depositSummary: string | null;
-        balanceSummary: string | null;
-        cancellationSummary: string | null;
-        paymentSummary: string | null;
+        depositSummary?: string | null;
+        balanceSummary?: string | null;
+        cancellationSummary?: string | null;
+        paymentSummary?: string | null;
     };
     operator?: {
-        body: string | null;
-        imageUrl: string | null;
-        aboutUrl: string | null;
-        licenceLabel: string | null;
-        officeLabel: string | null;
-        metrics: Array<{
-            value: string;
-            label: string;
+        body?: string | null;
+        imageUrl?: string | null;
+        aboutUrl?: string | null;
+        licenceLabel?: string | null;
+        officeLabel?: string | null;
+        metrics?: Array<{
+            value?: string;
+            label?: string;
         }>;
     };
-    goodToKnow: Array<{
-        title: string;
-        body: string;
-        ctaLabel: string | null;
-        href: string | null;
-        icon: 'info' | 'card' | 'shield' | 'globe' | 'people' | 'route' | null;
+    goodToKnow?: Array<{
+        title?: string;
+        body?: string;
+        ctaLabel?: string | null;
+        href?: string | null;
+        icon?: 'info' | 'card' | 'shield' | 'globe' | 'people' | 'route' | null;
     }>;
 };
 export type PublicDepartureListItem = {
@@ -301,21 +395,21 @@ export type PublicDepartureListItem = {
     startDate: string | null;
     endDate: string | null;
     availabilityStatus: 'Scheduled' | 'Guaranteed' | 'Sold Out';
-    priceDisplay: string | null;
+    priceDisplay?: string | null;
     currency: string | null;
-    bookingStatus: string | null;
+    bookingStatus?: string | null;
     state: PublicAvailabilityState;
     /** Places left, published only for the limited state (1 to 4); otherwise null. */
     left: number | null;
 };
 export type PublicTourQuestionListItem = {
     id: number;
-    askerName: string | null;
-    askedAt: string | null;
+    askerName?: string | null;
+    askedAt?: string | null;
     question: string;
     answer: string;
-    answeredByName: string | null;
-    answeredByRole: string | null;
+    answeredByName?: string | null;
+    answeredByRole?: string | null;
     answeredAt: string;
     /** Computed from (answeredAt - askedAt) at read time. Never a stored value. */
     answerTimeHours: number;
@@ -461,6 +555,11 @@ export type PublicAvailabilityListItem = {
     left: number | null;
     currency: string | null;
     priceDisplay: string | null;
+    /**
+     * Owner-approved controlled on-request price label when there is no fixed
+     * public price. Optional: older responses omit it.
+     */
+    priceOnRequestLabel?: string | null;
     priceDisplayByCurrency: PublicPriceDisplayByCurrency;
     promoLabel?: string | null;
     publicNote?: string | null;
@@ -535,8 +634,20 @@ export type PublicDestinationListItem = {
     id: number;
     slug: string;
     name: string;
+    /** Display title. Optional: older responses omit it. */
+    title?: string;
     summary: string | null;
-    heroImage: string | null;
+    /** Card excerpt. Optional: older responses omit it. */
+    excerpt?: string | null;
+    heroImage?: string | null;
+    /** Public hero image URL. Optional: older responses omit it. */
+    heroImageUrl?: string | null;
+    /** Display label. Optional: older responses omit it. */
+    destinationLabel?: string;
+    /** Canonical public page URL. Optional: older responses omit it. */
+    publicUrl?: string;
+    /** Call-to-action URL. Optional: older responses omit it. */
+    ctaUrl?: string;
     updatedAt: string | null;
     /** Optional so consumers stay compatible with servers predating the seo projection. */
     seo?: PublicSeo;
@@ -645,9 +756,9 @@ export type PublicCityDestinationContent = {
     closingBody?: string | null;
 };
 export type PublicDestinationDetail = PublicDestinationListItem & {
-    description: string | null;
-    seoTitle: string | null;
-    seoDescription: string | null;
+    description?: string | null;
+    seoTitle?: string | null;
+    seoDescription?: string | null;
     /** Operator-authored JSON-LD overrides from the published place profile. */
     structuredDataOverrides?: Record<string, unknown> | null;
     /** Absent for a legacy row, an unpublished profile, or a database without the City schema. */
@@ -1711,6 +1822,12 @@ export type PublicSiteTrustPageContent = {
     cta: PublicSiteCta | null;
     sections: PublicSiteTrustSection[];
     seo: PublicSiteTrustPageSeo;
+    /**
+     * Published registry-driven block composition for this page, when one
+     * exists. Additive and optional: a consumer that predates blocks is
+     * unaffected, and a page with no composition is unchanged.
+     */
+    blocks?: PublicSiteBlock[];
 };
 export type PublicSiteTrustPageContentResponse = {
     data: PublicSiteTrustPageContent | null;

package/dist/types.js

@@ -1,3 +1,7 @@
-// Hand-maintained public API types; generated contract types live in src/generated/public-api-v1.ts.
+// Hand-maintained public API types. Generated from the contract snapshot:
+// src/generated/public-api-v1.ts (path, operation and schema name lists, published)
+// and src/generated/public-api-v1.schema.ts (full openapi-typescript types, not
+// published). test/types-conformance.ts checks every type here whose name matches
+// a contract schema against the generated one; known deviations are allowlisted there.
 // Zero runtime code. Types only.
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surfiran/public-api-client",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "TypeScript types and client for SURFIRAN CRM Public API V1",
   "type": "module",
   "engines": {
@@ -45,9 +45,9 @@
   ],
   "scripts": {
     "build": "node scripts/build.cjs",
-    "generate": "node scripts/generate-public-api-v1.cjs",
+    "generate": "node scripts/generate-public-api-v1.cjs && node scripts/generate-public-api-v1-schema.cjs",
     "prepack": "npm run verify:contract && npm run verify:package && npm run verify:repository && npm run verify:generated && npm run typecheck && npm test && npm run build",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.conformance.json",
     "test": "vitest run",
     "verify:contract": "node scripts/verify-contract.cjs",
     "verify:api-contract-artifact": "node scripts/verify-api-contract-artifact.cjs",
@@ -63,6 +63,7 @@
   },
   "dependencies": {},
   "devDependencies": {
+    "openapi-typescript": "7.13.0",
     "typescript": "^5.2.2",
     "vitest": "^4.1.8"
   }