@surfiran/public-api-client 0.30.0 → 0.31.0

package/README.md

@@ -1,6 +1,6 @@
 # Public API Client
 
-Zero-runtime-dependency TypeScript types and fetch client for SURFIRAN Public API V1. The checked-in package-local contract snapshot is OpenAPI `v0.19.0`.
+Zero-runtime-dependency TypeScript types and fetch client for SURFIRAN Public API V1. The checked-in package-local contract snapshot is OpenAPI `v0.22.0`.
 
 Repository: `SURFIRAN/surfiran-public-api-client`
 
@@ -18,7 +18,7 @@ The repository split and production cutover are complete. This repository is the
 
 `contract/public-api-v1.yaml` is the package-local immutable snapshot used for generation. `contract/provenance.json` records its source identity, immutable source revision, checksums, and, for standalone releases, the exact API artifact identity.
 
-The checked-in `0.30.0` snapshot and provenance come from the `SURFIRAN/surfiran-crm-api` main-branch release `public-api-contract/b4ffb56bc203317ce25ec261a4f64df661c91f53-37147490534-1`. Published `0.20.0` and earlier keep their historical provenance, which may still reference the former monorepo owner or path. Do not rewrite an already published package version solely to rename historical provenance.
+The checked-in `0.31.0` snapshot and provenance come from the `SURFIRAN/surfiran-crm-api` main-branch release `public-api-contract/ce5f1c0231e47dd3d438d8e43cdeab899b5b9d45-37219746311-1`. Published `0.20.0` and earlier keep their historical provenance, which may still reference the former monorepo owner or path. Do not rewrite an already published package version solely to rename historical provenance.
 
 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.
 
@@ -94,6 +94,6 @@ Published versions are immutable. Rollback means pinning consumers to the previo
 - This README owns local setup, contract synchronization, CI, publication, and rollback guidance.
 - [AGENTS.md](AGENTS.md) owns agent operating instructions.
 - [Repository boundaries and documentation governance](https://github.com/SURFIRAN/surfiran-crm-api/blob/main/docs/architecture/REPOSITORY_BOUNDARIES.md) own shared architecture and current system state.
-- [Contract snapshot](contract/public-api-v1.yaml) and [provenance](contract/provenance.json) are immutable evidence for `0.30.0`, not current API ownership authorities.
+- [Contract snapshot](contract/public-api-v1.yaml) and [provenance](contract/provenance.json) are immutable evidence for `0.31.0`, not current API ownership authorities.
 
 Update existing guidance instead of creating duplicate contract or publication authorities. Preserve the historical snapshot, provenance, and generated bytes until a reviewed new package version imports a verified API artifact.

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

@@ -1,4 +1,4 @@
-export type GeneratedPublicApiVersion = '0.19.0';
+export type GeneratedPublicApiVersion = '0.22.0';
 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' | '/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}/preview' | '/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 /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}/preview' | '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 /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 /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}/preview' | '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 /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, 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, PublicDepartureListResponse, PublicDestinationListResponse, PublicDestinationDetailResponse, PublicApiResult, ListPublicToursParams, GetPublicTourParams, GetPublicDestinationParams, PublicContentLocale, GetPublicTourPreviewParams, ListPublicDeparturesParams, ListPublicTourAvailabilityParams, ListPublicDestinationsParams, PublicInquiryRequest, PublicTourTailorJourney, PublicInquiryResponse, PublicSupportRequestCategory, PublicSupportRequest, PublicSupportRequestRecaptcha, PublicSupportRequestResponse, PublicMarketingUnsubscribeRequest, PublicMarketingUnsubscribeResponse, 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, 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, PublicDepartureListItem, PublicAvailabilityStatus, PublicAvailabilityListItem, PublicAvailabilityListResponse, PublicDestinationListItem, PublicCityDestinationContent, PublicCityExperience, PublicCityImage, PublicCityLabelledValue, PublicCityLink, PublicCityNextPlace, PublicCityReason, PublicCityResource, PublicCityStayLink, PublicDestinationDetail, PublicTourListResponse, PublicTourCatalogMetadata, PublicTourCatalogFacetKey, PublicTourCatalogFacetOption, PublicTourCatalogSort, PublicTourCatalogStartingFrom, PublicTourCatalogDepartureSummary, PublicTourDetailResponse, PublicDepartureListResponse, PublicDestinationListResponse, PublicDestinationDetailResponse, PublicApiResult, ListPublicToursParams, GetPublicTourParams, GetPublicDestinationParams, PublicContentLocale, GetPublicTourPreviewParams, ListPublicDeparturesParams, ListPublicTourAvailabilityParams, ListPublicDestinationsParams, PublicInquiryRequest, PublicTourTailorJourney, PublicInquiryResponse, PublicSupportRequestCategory, PublicSupportRequest, PublicSupportRequestRecaptcha, PublicSupportRequestResponse, PublicMarketingUnsubscribeRequest, PublicMarketingUnsubscribeResponse, 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, 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

@@ -65,6 +65,11 @@ export type PublicPriceDisplayByCurrency = {
     EUR: string | null;
     GBP: string | null;
 };
+/**
+ * Server-owned geographic classification of a tour: `iran` for an Iran-only
+ * route, `beyond-iran` for one that reaches past Iran.
+ */
+export type PublicTourRegion = 'iran' | 'beyond-iran';
 export type PublicTourListItem = {
     /** Published dates, independent of capacity; present in catalog mode. */
     departureSummary?: PublicTourCatalogDepartureSummary;
@@ -107,6 +112,12 @@ export type PublicTourListItem = {
      * absent, so a consumer never needs a null check before reading `.length`.
      */
     countries: string[];
+    /**
+     * Server-owned region classification of this tour. The CRM API decides it;
+     * clients must not re-derive it from `countries`, `beyondIran`, or
+     * destinations, and should render and filter on this value as published.
+     */
+    region: PublicTourRegion;
     /**
      * 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"
@@ -137,6 +148,13 @@ export type PublicTourListItem = {
      * environment predating the migration still answers; absent means false.
      */
     isSignature?: boolean;
+    /**
+     * Operator-published Signature band position: a positive integer, or null
+     * when the tour is not ranked. Used with `isSignature` and the
+     * `signature-rank` catalog sort. Optional so a response projected before this
+     * field existed still typechecks.
+     */
+    signatureRank?: number | null;
     /** Reserved for future backend-verified historical price data. Currently always null. */
     previousPriceDisplay?: string | null;
     /** Reserved for a future backend-verified promotion label. Currently always null. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surfiran/public-api-client",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "TypeScript types and client for SURFIRAN CRM Public API V1",
   "type": "module",
   "engines": {