@garagem-ai/site-sdk 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { F as FetchLike, R as RequestNextOptions, L as ListingDetail, a as ListingLocation, b as ListingMedia, c as ListingBusinessType, d as ListingPriceVisibility, e as Listing, S as SearchPathFilters, f as SearchUiDictionary, Q as QueryListingsFilters, A as AppliedSearchQuery, g as AppliedSearchChange, h as ListingFilters, i as ListingsResult, j as Site, k as SearchListingsParams, l as SearchListingsResult, m as SearchUi, n as QueryListingsParams, o as QueryListingsResult, p as SimilarListingsResult, C as CmsCollection, q as CmsEntriesResult, r as CmsEntry, P as PhotoSearchParams, s as PhotoSearchResult, t as PhotoSearchItem, u as ListingWithMatchedPhoto, M as MatchedListingPhoto } from './types-photo-search-OeONNDxl.js';
2
- export { v as CmsEntryStatus, w as CmsFieldDefinition, x as CmsFieldType, y as CmsSeoData, z as FORBIDDEN_SEARCH_QUERY_KEYS, G as GaragemSdkError, B as GetCmsCollectionOptions, D as GetCmsCollectionsOptions, E as GetCmsEntriesOptions, H as GetCmsEntryOptions, I as GetListingOptions, J as GetListingsOptions, K as GetSearchUiOptions, N as GetSimilarListingsOptions, O as GetSiteOptions, T as ListingPropertySummary, U as LocationNameTables, V as QueryListingsLocation, W as QueryListingsOptions, X as SEARCH_EMPTY_COPY, Y as SEARCH_SORT_RELEVANCE, Z as SearchChromeModel, _ as SearchListingsOptions, $ as SearchPathLocation, a0 as SearchUiFilter, a1 as SearchUiOption, a2 as TOOLBAR_PRIMARY_FILTER_IDS, a3 as applyPathFilter, a4 as buildQueryListingsParams, a5 as canonicalizeSearchHref, a6 as clearStagedPathFilters, a7 as countFacetChoices, a8 as countOptionLabel, a9 as displayPathLocation, aa as getCmsCollection, ab as getCmsCollections, ac as getCmsEntries, ad as getCmsEntry, ae as getListing, af as getListings, ag as getSearchUi, ah as getSimilarListings, ai as getSite, aj as hrefForAppliedChange, ak as hrefForPathFilters, al as hrefWithExplicitPage, am as isListingDetailPath, an as paginationPages, ao as pathFilterHasOption, ap as pathFilterValue, aq as publicSearchHref, ar as queryListings, as as rangeDraftFromPath, at as readPublicSearch, au as searchChromeModel, av as searchHrefUsesLegacyFilterQuery, aw as searchListings, ax as searchResultsHeading, ay as searchSortOptions, az as toolbarFilterIds, aA as visibleSearchFilters } from './types-photo-search-OeONNDxl.js';
1
+ import { F as FetchLike, R as RequestNextOptions, L as ListingDetail, a as ListingLocation, b as ListingMedia, S as SearchPathFilters, c as SearchUiDictionary, Q as QueryListingsFilters, A as AppliedSearchQuery, d as AppliedSearchChange, e as ListingFilters, f as ListingsResult, g as Site, h as SearchListingsParams, i as SearchListingsResult, j as SearchUi, k as QueryListingsParams, l as QueryListingsResult, m as SimilarListingsResult, C as CmsCollection, n as CmsEntriesResult, o as CmsEntry, B as BoundaryCity, p as BoundaryLayerOptions, M as MapsCoordinates, T as TravelTimeCacheOptions, q as TravelTimeCache, r as MapsFetchOptions, s as BoundaryLayer, t as ListingWithLocation, u as StaticMapOptions, v as StreetViewAvailabilityOptions, w as StreetViewAvailability, x as StreetViewOptions, N as NeighborhoodBoundaryOptions, y as NeighborhoodBoundary, z as TravelDestination, D as TravelMode, E as TravelTimeOptions, G as TravelTime, H as TravelTimesOptions, I as TravelTimeElement, J as Listing, P as PhotoSearchParams, K as PhotoSearchResult, O as PhotoSearchItem, U as ListingWithMatchedPhoto, V as MatchedListingPhoto } from './types-photo-search-D88oevZv.js';
2
+ export { W as BoundaryFeature, X as BoundaryFeatureCollection, Y as BoundaryGeometry, Z as BoundaryLayerUrlKind, _ as BoundarySourceLayer, $ as CmsEntryStatus, a0 as CmsFieldDefinition, a1 as CmsFieldType, a2 as CmsSeoData, a3 as FORBIDDEN_SEARCH_QUERY_KEYS, a4 as GaragemSdkError, a5 as GetCmsCollectionOptions, a6 as GetCmsCollectionsOptions, a7 as GetCmsEntriesOptions, a8 as GetCmsEntryOptions, a9 as GetListingOptions, aa as GetListingsOptions, ab as GetSearchUiOptions, ac as GetSimilarListingsOptions, ad as GetSiteOptions, ae as ListingBusinessType, af as ListingCardModel, ag as ListingPriceVisibility, ah as ListingPropertySummary, ai as LocationNameTables, aj as MAP_POLYGON_MAX_VERTICES, ak as MAP_SEARCH_DEFAULT_PAGE_SIZE, al as MAP_SEARCH_MAX_PAGE_SIZE, am as MAP_VIEWPORT_DEBOUNCE_MS, an as MapBounds, ao as MapBoundsSearchOptions, ap as MapPin, aq as MapPinCluster, ar as MapPolygon, as as MapPolygonSearchOptions, at as MapSearchResult, au as MapsBaseOptions, av as QueryListingsLocation, aw as QueryListingsOptions, ax as SEARCH_EMPTY_COPY, ay as SEARCH_SORT_RELEVANCE, az as SearchChromeModel, aA as SearchListingsOptions, aB as SearchPathLocation, aC as SearchUiFilter, aD as SearchUiOption, aE as StaticMapStyle, aF as TOOLBAR_PRIMARY_FILTER_IDS, aG as applyPathFilter, aH as buildQueryListingsParams, aI as canonicalizeSearchHref, aJ as capMapPage, aK as capMapPageSize, aL as clearStagedPathFilters, aM as clusterPins, aN as countFacetChoices, aO as countOptionLabel, aP as displayPathLocation, aQ as getCmsCollection, aR as getCmsCollections, aS as getCmsEntries, aT as getCmsEntry, aU as getListing, aV as getListings, aW as getSearchUi, aX as getSimilarListings, aY as getSite, aZ as hrefForAppliedChange, a_ as hrefForPathFilters, a$ as hrefWithExplicitPage, b0 as isListingDetailPath, b1 as isMapBounds, b2 as isMapPolygon, b3 as listingLocationLabel, b4 as mapClusterCellDegrees, b5 as mapSearchPins, b6 as paginationPages, b7 as pathFilterHasOption, b8 as pathFilterValue, b9 as publicSearchHref, ba as queryListings, bb as rangeDraftFromPath, bc as readPublicSearch, bd as searchChromeModel, be as searchHrefUsesLegacyFilterQuery, bf as searchListings, bg as searchListingsInBounds, bh as searchListingsInPolygon, bi as searchResultsHeading, bj as searchSortOptions, bk as toListingCardModel, bl as toolbarFilterIds, bm as visibleSearchFilters } from './types-photo-search-D88oevZv.js';
3
3
 
4
4
  /**
5
5
  * Visit-lead schedule: hours in, slots out. Pure — no fetch, no React.
@@ -68,6 +68,8 @@ type GetLeadUiOptions = {
68
68
  baseUrl?: string;
69
69
  fetch?: FetchLike;
70
70
  next?: RequestNextOptions;
71
+ /** Site publishable key (`pk_live_…`). Not a secret. */
72
+ publishableKey?: string;
71
73
  };
72
74
  type LeadContact = {
73
75
  name: string;
@@ -79,6 +81,8 @@ type LeadSubmitBase = LeadContact & {
79
81
  siteId?: string | Promise<string>;
80
82
  baseUrl?: string;
81
83
  fetch?: FetchLike;
84
+ /** Site publishable key (`pk_live_…`). Not a secret. */
85
+ publishableKey?: string;
82
86
  listingId: string;
83
87
  /**
84
88
  * Active listing modality (`sale` | `rental` | `rent`). Always pass
@@ -102,11 +106,13 @@ type LeadSubmitResult = {
102
106
  status: 202;
103
107
  id: string;
104
108
  };
105
- type LeadSubmitErrorCode = "invalid_listing_id" | "invalid_contact" | "invalid_slot" | "rate_limited" | "not_found" | "http" | "network";
109
+ type LeadSubmitErrorCode = "invalid_listing_id" | "invalid_contact" | "invalid_slot" | "unauthorized" | "rate_limited" | "not_found" | "http" | "network";
106
110
  declare class LeadSubmitError extends Error {
107
111
  readonly code: LeadSubmitErrorCode;
108
112
  readonly status?: number;
109
113
  readonly retryAfterSeconds?: number;
114
+ /** Seconds to wait. Same value as `retryAfterSeconds`; `null` when unset. */
115
+ readonly retryAfter: number | null;
110
116
  constructor(message: string, info: {
111
117
  code: LeadSubmitErrorCode;
112
118
  status?: number;
@@ -273,46 +279,6 @@ type ListingDetailFieldsSource = ListingAmenitySource & Pick<ListingDetail, "pri
273
279
  */
274
280
  declare function listingDetailFieldsModel(listing: ListingDetailFieldsSource, dictionary?: AmenityLabelDictionary): ListingDetailFieldsModel;
275
281
 
276
- /** Fields every listing card must have — no JSX. */
277
- type ListingCardModel = {
278
- href: string;
279
- title: string;
280
- businessType: ListingBusinessType;
281
- businessLabel: string;
282
- priceVisibility: ListingPriceVisibility;
283
- price: number | null;
284
- priceLabel: string;
285
- pricePeriod: string | null;
286
- locationLabel: string;
287
- propertyType: string | null;
288
- coverSrc: string | null;
289
- coverAlt: string;
290
- bedrooms: number | null;
291
- bathrooms: number | null;
292
- parkingSpaces: number | null;
293
- areaM2: number | null;
294
- };
295
- declare function listingLocationLabel(location: {
296
- neighborhood?: string | null;
297
- city?: string | null;
298
- state?: string | null;
299
- }): string;
300
- declare function toListingCardModel(listing: Pick<Listing, "id" | "listingCode" | "path" | "title" | "businessType" | "price" | "currency" | "priceVisibility" | "coverImage"> & {
301
- property?: {
302
- type?: string | null;
303
- bedrooms?: number | null;
304
- bathrooms?: number | null;
305
- parkingSpaces?: number | null;
306
- usableArea?: number | null;
307
- totalArea?: number | null;
308
- };
309
- location?: {
310
- neighborhood?: string | null;
311
- city?: string | null;
312
- state?: string | null;
313
- };
314
- }): ListingCardModel;
315
-
316
282
  /**
317
283
  * Presentation helpers with no UI framework.
318
284
  * Adapters consume these formatters; they must not live inside JSX.
@@ -442,6 +408,8 @@ interface ResolvePublicSiteIdOptions {
442
408
  fallback?: string | null;
443
409
  baseUrl?: string;
444
410
  fetch?: FetchLike;
411
+ /** Forwarded to `getSite` when the live host is resolved. */
412
+ publishableKey?: string;
445
413
  }
446
414
  declare function isStudioPreviewHost(host: string): boolean;
447
415
  /**
@@ -502,6 +470,24 @@ declare const STUDIO_SDK_CONTRACT: {
502
470
  */
503
471
  readonly unpublishedPhoneExports: readonly [];
504
472
  readonly amenityExports: readonly ["listingAmenityGroups"];
473
+ /**
474
+ * Prompt-safe photo helpers on `minNpmVersion`. Empty until the release
475
+ * that carries `getSimilarByPhoto` / `listingPhotoGroups` /
476
+ * `listingVisualHighlights` is on npm; then bump the pin, move the names
477
+ * here from `unpublishedPhotoExports`, and `studioPhotoInstruction()`
478
+ * starts teaching the gallery-by-room, highlight chips, and
479
+ * "imóveis com fotos parecidas" blocks. The caption-based `media[].alt` /
480
+ * `media[].caption` fields are API data (not tarball exports) and are
481
+ * documented regardless of the pin.
482
+ */
483
+ readonly photoExports: readonly [];
484
+ /**
485
+ * Photo helpers in the repo but not on `minNpmVersion`. Prompts,
486
+ * completeness, and repair text must not mention these until the pin
487
+ * bumps — v0 installs the pin and the ESM loader throws on missing named
488
+ * exports.
489
+ */
490
+ readonly unpublishedPhotoExports: readonly ["getSimilarByPhoto", "listingPhotoGroups", "listingVisualHighlights", "photoRoomLabel"];
505
491
  /**
506
492
  * Names already on the pinned npm tarball (`minNpmVersion`) — safe for
507
493
  * Studio prompts and completeness. Includes `visibleSearchFilters` +
@@ -516,6 +502,17 @@ declare const STUDIO_SDK_CONTRACT: {
516
502
  * already listed in `searchExports`.
517
503
  */
518
504
  readonly unpublishedSearchExports: readonly ["searchChromeModel", "rangeDraftFromPath"];
505
+ /**
506
+ * maps.fndn.ai helpers (static map, street view, boundaries, travel
507
+ * time) plus friendly map search. They ship in `mapsSince`;
508
+ * `studioMapsInstruction()` is empty and these names are codegen
509
+ * violations until `minNpmVersion` reaches that release — bump the pin
510
+ * after the tarball is on npm and the listing guidance turns on by
511
+ * itself. `useMapSearch` is a `/react` hook named in that same
512
+ * instruction; it stays off `reactExports` until the pin moves.
513
+ */
514
+ readonly mapsSince: "0.7.0";
515
+ readonly mapsExports: readonly ["listingStaticMapUrl", "listingStreetViewUrl", "listingStreetViewAvailable", "neighborhoodBoundaryLayer", "boundaryLayerUrl", "travelTimeFromListing", "searchListingsInBounds", "searchListingsInPolygon", "clusterPins"];
519
516
  /**
520
517
  * Market-data helpers (neighborhood price summary, listing market
521
518
  * position, visitor price estimate, pt-BR labels). They ship in
@@ -567,12 +564,38 @@ declare function coerceNpmVersion(raw: unknown): string | null;
567
564
  declare function compareSemver(a: string, b: string): number;
568
565
  declare function parseReactSdkNamedImports(source: string): string[];
569
566
  declare function unavailableReactImports(source: string, pin: string): string[];
567
+ /**
568
+ * Studio copy for the public site API key. Names only exports that already
569
+ * exist on `minNpmVersion` (`createGaragemClient`, `GaragemSdkError`,
570
+ * `usePublicSearch`, the lead helpers). `publishableKey` is an extra option
571
+ * older tarballs ignore, so generated sites keep working before this SDK
572
+ * version is published.
573
+ */
574
+ declare function studioPublishableKeyInstruction(): string;
570
575
  declare function studioSdkPinInstruction(): string;
571
576
  declare function studioLeadInstruction(): string;
572
577
  declare function studioListingCardInstruction(): string;
573
578
  declare function studioListingDetailInstruction(): string;
579
+ /**
580
+ * Listing-detail photo intelligence, gated on the published pin. The base
581
+ * sentence (caption-based `alt` / optional `caption` on gallery photos) is
582
+ * API data and always applies; each helper block appears only when its
583
+ * export is in `published` (see `STUDIO_SDK_CONTRACT.photoExports`).
584
+ */
585
+ declare function studioPhotoInstructionFor(published: readonly string[]): string;
586
+ declare function studioPhotoInstruction(): string;
574
587
  declare function studioAmenityInstruction(): string;
575
588
  declare function studioSearchInstruction(): string;
589
+ /** Whether the Studio pin already carries the maps helpers. */
590
+ declare function mapsExportsPublished(pin?: string): boolean;
591
+ /**
592
+ * Listing-detail maps guidance. Empty while the pinned tarball predates
593
+ * `mapsSince`, because v0 copies every identifier it reads and the preview
594
+ * ESM loader throws on a missing named export.
595
+ */
596
+ declare function studioMapsInstruction(options?: {
597
+ pin?: string;
598
+ }): string;
576
599
  /** True when the pinned tarball ships the market-data helpers. */
577
600
  declare function marketExportsAvailableAt(pin: string): boolean;
578
601
  /**
@@ -599,6 +622,12 @@ interface CreateGaragemClientOptions {
599
622
  baseUrl?: string;
600
623
  /** Pre-bind a site so each call doesn't repeat it. */
601
624
  siteId?: string;
625
+ /**
626
+ * Publishable key (`pk_live_…`) from the site's API pública settings.
627
+ * Sent as `X-Garagem-Publishable-Key` on every request. Not a secret.
628
+ * Omit it to keep the anonymous per-IP budget.
629
+ */
630
+ publishableKey?: string;
602
631
  /** Custom fetch implementation. */
603
632
  fetch?: FetchLike;
604
633
  /** Default Next.js caching hints applied to every request. */
@@ -701,6 +730,238 @@ interface GaragemClient {
701
730
  * exported for the no-client style.
702
731
  */
703
732
  declare function createGaragemClient(options?: CreateGaragemClientOptions): GaragemClient;
733
+ /**
734
+ * Alias of {@link createGaragemClient}. `createClient({ publishableKey })`
735
+ * binds the key the same way.
736
+ */
737
+ declare const createClient: typeof createGaragemClient;
738
+
739
+ /**
740
+ * maps.fndn.ai helpers: static map / street view image URLs, boundary
741
+ * layers for MapLibre, and travel time. All of them consume the coordinates
742
+ * the public listings API already masked for the site — nothing here calls
743
+ * Google directly or adds precision.
744
+ *
745
+ * URL shapes mirror `@garagem/geo` (`buildGoogleStaticMapImageUrl`,
746
+ * `buildStreetViewImageUrl`); the SDK keeps its own copy because the
747
+ * published package cannot bundle the private geo workspace package. A
748
+ * parity test in `tests/maps-geo-parity.test.ts` keeps the two in sync.
749
+ */
750
+
751
+ declare const DEFAULT_MAPS_BASE_URL = "https://maps.fndn.ai";
752
+ /** Header maps.fndn.ai meters per site. Mirrors `apps/maps` `SITE_HEADER`. */
753
+ declare const MAPS_SITE_HEADER = "X-Garagem-Site";
754
+ /** Google Static Maps / Street View Static edge ceiling. */
755
+ declare const MAPS_MAX_IMAGE_EDGE = 640;
756
+ /**
757
+ * Coordinates the public API returned for a listing, or `null` when the
758
+ * listing has none (or a `0,0` placeholder). Values are passed through
759
+ * untouched — they are already masked per the site's precision setting.
760
+ */
761
+ declare function listingCoordinates(listing: ListingWithLocation): MapsCoordinates | null;
762
+ /** Number of decimal places carried by a coordinate (`-23.55` → 2). */
763
+ declare function coordinateDecimals(value: number): number;
764
+ /**
765
+ * Reduce coordinates to at most `maxDecimals` places. Never adds precision:
766
+ * a point the API already masked to 3 decimals stays at 3 when asked for 6.
767
+ */
768
+ declare function coarsenCoordinates(coordinates: MapsCoordinates, maxDecimals: number | undefined): MapsCoordinates;
769
+ /**
770
+ * Highest zoom that does not overstate the precision of the coordinates.
771
+ * 3 decimals (≈100 m, the public default) caps at 16; 2 (≈1 km) at 13;
772
+ * 1 or fewer at 11; 4+ decimals get the full Google range (21).
773
+ */
774
+ declare function maxZoomForCoordinates(coordinates: MapsCoordinates): number;
775
+ declare function normalizeMapsBaseUrl(baseUrl: string | undefined): string;
776
+ /**
777
+ * `GET /v1/static-map` URL for an `<img>`. Returns `null` when the listing
778
+ * has no public coordinates. Zoom is capped by the coordinate precision.
779
+ */
780
+ declare function listingStaticMapUrl(listing: ListingWithLocation, options?: StaticMapOptions): string | null;
781
+ /**
782
+ * `GET /v1/street-view` URL for an `<img>`. Returns `null` when the listing
783
+ * has no public coordinates. Google picks the nearest panorama to the
784
+ * (masked) point, so pair it with `listingStreetViewAvailable`.
785
+ */
786
+ declare function listingStreetViewUrl(listing: ListingWithLocation, options?: StreetViewOptions): string | null;
787
+ /** `GET /v1/street-view/metadata` URL (free on Google's side). */
788
+ declare function listingStreetViewMetadataUrl(listing: ListingWithLocation, options?: StreetViewAvailabilityOptions): string | null;
789
+ /**
790
+ * Whether Google has a panorama near the listing. Metadata lookups are free,
791
+ * so call this before rendering `listingStreetViewUrl` (which is billed).
792
+ * Network failures resolve to `{ available: false, status: "ERROR" }`.
793
+ */
794
+ declare function listingStreetViewAvailable(listing: ListingWithLocation, options?: StreetViewAvailabilityOptions): Promise<StreetViewAvailability>;
795
+ /** `"São Paulo"` → `sao_paulo`; existing slugs pass through. */
796
+ declare function boundaryCitySlug(city: string): string;
797
+ /** maps.fndn.ai layer id for a city's boundaries (`sao_paulo_boundaries`). */
798
+ declare function boundaryLayerId(city: BoundaryCity): string;
799
+ /**
800
+ * URL for a city's boundary layer. `kind` picks the representation:
801
+ * `tilejson` (default) for MapLibre vector sources, `tiles` for the raw
802
+ * `{z}/{x}/{y}` template, `geojson` for the whole city, `layer` for the
803
+ * descriptor served by `/v1/layers/:id`.
804
+ */
805
+ declare function boundaryLayerUrl(city: BoundaryCity, options?: BoundaryLayerOptions): string;
806
+ /** GeoJSON URL for one named outline (`/api/boundaries/:city/:name`). */
807
+ declare function neighborhoodBoundaryUrl(city: BoundaryCity, neighborhood: string, options?: NeighborhoodBoundaryOptions): string;
808
+ /** Fetch the layer descriptor (`/v1/layers/:id`). `null` when unknown. */
809
+ declare function getBoundaryLayer(city: BoundaryCity, options?: MapsFetchOptions): Promise<BoundaryLayer | null>;
810
+ /**
811
+ * Resolve a neighbourhood outline so a site map can draw it. maps.fndn.ai
812
+ * matches the name case-insensitively: an exact match returns one feature,
813
+ * a partial match may return several (`candidates`), none returns
814
+ * `feature: null`.
815
+ */
816
+ declare function neighborhoodBoundaryLayer(city: BoundaryCity, neighborhood: string, options?: NeighborhoodBoundaryOptions): Promise<NeighborhoodBoundary>;
817
+ /** Small LRU with TTL. Lives per module instance (one per page/worker). */
818
+ declare function createTravelTimeCache(options?: TravelTimeCacheOptions): TravelTimeCache;
819
+ /** Drop every cached travel time (tests, or after a listing moves). */
820
+ declare function clearTravelTimeCache(): void;
821
+ declare function travelTimeCacheKey(origin: MapsCoordinates, destination: MapsCoordinates, mode: TravelMode): string;
822
+ /**
823
+ * Resolve a free-text destination through `/v1/geocode` (Nominatim first,
824
+ * so usually free). Coordinates pass through.
825
+ */
826
+ declare function resolveTravelDestination(destination: TravelDestination, options?: MapsFetchOptions): Promise<MapsCoordinates | null>;
827
+ /**
828
+ * Travel time from the listing's (masked) coordinates to a destination via
829
+ * `GET /v1/directions`. Each uncached call is one Google Directions request
830
+ * on the shared key (≈US$5 per 1 000 at list price, metered per site when
831
+ * `siteId` is set). Cache hits are free, including the geocode a string
832
+ * destination would otherwise spend. Returns `null` when the listing has no
833
+ * coordinates, the destination cannot be resolved, or no route exists.
834
+ */
835
+ declare function travelTimeFromListing(listing: ListingWithLocation, destination: TravelDestination, options?: TravelTimeOptions): Promise<TravelTime | null>;
836
+ /**
837
+ * Driving time from the listing to many destinations in one
838
+ * `POST /v1/route-matrix` call (Google Route Matrix, billed per element:
839
+ * ≈US$5 per 1 000 at list price). Distances are not returned by the matrix.
840
+ * Element is `null` when Google found no route; the whole result is `null`
841
+ * when the listing has no coordinates or the request failed.
842
+ */
843
+ declare function travelTimesFromListing(listing: ListingWithLocation, destinations: MapsCoordinates[], options?: TravelTimesOptions): Promise<Array<TravelTimeElement | null> | null>;
844
+
845
+ /**
846
+ * Photo intelligence types for the public Sites API.
847
+ *
848
+ * `ListingMedia` (in `./types`) carries the per-photo analysis on the listing
849
+ * detail; these shapes cover the "imóveis com fotos parecidas" endpoint and
850
+ * the headless photo helpers. Additive contract, never breaking.
851
+ */
852
+
853
+ /** The photo of a similar listing that matched the reference photo. */
854
+ interface SimilarPhotoMatch {
855
+ /** Media id of the matched photo on the similar listing. */
856
+ id: string;
857
+ src: string;
858
+ alt: string;
859
+ /** AI caption of the matched photo, when it has one. */
860
+ caption: string | null;
861
+ /** Typesense cosine `vector_distance`; lower is closer. `null` when unknown. */
862
+ distance: number | null;
863
+ }
864
+ interface SimilarByPhotoItem {
865
+ /** Same card shape as `getListings`. */
866
+ listing: Listing;
867
+ matchedPhoto: SimilarPhotoMatch;
868
+ }
869
+ /** Response of `getSimilarByPhoto`. */
870
+ interface SimilarByPhotoResult {
871
+ /**
872
+ * `false` when the site's tenant has no image search, or when `mediaId`
873
+ * is not a media UUID (the `image-N` / `external-N` gallery keys). Hide
874
+ * the block instead of rendering an empty carousel.
875
+ */
876
+ available: boolean;
877
+ items: SimilarByPhotoItem[];
878
+ }
879
+ /** Gallery photos of one room type, in gallery order. */
880
+ interface ListingPhotoGroup {
881
+ /** Normalized key (`quarto`, `sala`, `cozinha`, …; `outros` for unknown). */
882
+ key: string;
883
+ /** pt-BR label ready to render (`Quartos`, `Sala`, `Cozinha`, …). */
884
+ label: string;
885
+ photos: ListingMedia[];
886
+ }
887
+
888
+ /**
889
+ * "Imóveis com fotos parecidas" fetcher.
890
+ *
891
+ * Self-contained beside `./fetchers`: same base-URL / fetch / `next`
892
+ * conventions, positional ids so a gallery click can call
893
+ * `getSimilarByPhoto(siteId, listing.id, photo.id)` directly.
894
+ */
895
+
896
+ interface GetSimilarByPhotoOptions {
897
+ /** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
898
+ baseUrl?: string;
899
+ /** Override the fetch implementation (testing, edge runtimes, retries). */
900
+ fetch?: FetchLike;
901
+ /** Next.js App Router caching hints. Ignored elsewhere. */
902
+ next?: RequestNextOptions;
903
+ /** Max similar listings to return (API default 6, cap 12). */
904
+ limit?: number;
905
+ }
906
+ /**
907
+ * Listings whose public photos look like one photo of `listingId`.
908
+ *
909
+ * `available` is `false` when the site's tenant has no image search, and
910
+ * when `mediaId` is not a media UUID (`image-N`, `external-N`, or any other
911
+ * gallery key `getListing` assigned). That case returns locally, without a
912
+ * request, so a page that passes `photo.id` hides the block instead of
913
+ * throwing. Items carry the public card model plus the photo that matched.
914
+ *
915
+ * @example
916
+ * const { available, items } = await getSimilarByPhoto(
917
+ * siteId,
918
+ * listing.id,
919
+ * photo.id,
920
+ * { limit: 6, next: { revalidate: 300 } }
921
+ * );
922
+ */
923
+ declare function getSimilarByPhoto(siteId: string, listingId: string, mediaId: string, options?: GetSimilarByPhotoOptions): Promise<SimilarByPhotoResult>;
924
+
925
+ /**
926
+ * Headless photo helpers for the listing detail.
927
+ *
928
+ * `listingPhotoGroups` turns the gallery into "Sala (3) · Quartos (4) ·
929
+ * Cozinha (2)" sections from the per-photo `roomType`; `listingVisualHighlights`
930
+ * surfaces the visual features the analysis named most often. Both are pure
931
+ * and only read `ListingDetail.media`.
932
+ */
933
+
934
+ declare const PHOTO_GROUP_OTHER_KEY = "outros";
935
+ declare const PHOTO_GROUP_OTHER_LABEL = "Outras fotos";
936
+ /**
937
+ * Group key + pt-BR label for a photo `roomType`. Unknown rooms keep their
938
+ * own (capitalized) label; empty / "other" values go to `Outras fotos`.
939
+ */
940
+ declare function photoRoomLabel(roomType: string | null | undefined): {
941
+ key: string;
942
+ label: string;
943
+ };
944
+ /**
945
+ * Gallery photos grouped by room, in first-appearance order with `Outras
946
+ * fotos` last. Videos and tours are skipped. A listing with no analysis at
947
+ * all yields a single `Outras fotos` group (or `[]` when it has no photos),
948
+ * so callers can fall back to the flat gallery when `groups.length <= 1`.
949
+ */
950
+ declare function listingPhotoGroups(listing: {
951
+ media?: ListingMedia[] | null;
952
+ }): ListingPhotoGroup[];
953
+ interface ListingVisualHighlightsOptions {
954
+ /** Max highlights to return. Default 8. */
955
+ limit?: number;
956
+ }
957
+ /**
958
+ * Distinct visual highlights across the gallery, most frequent first (ties
959
+ * keep gallery order). Case- and accent-insensitive dedupe; the first
960
+ * spelling seen wins.
961
+ */
962
+ declare function listingVisualHighlights(listing: {
963
+ media?: ListingMedia[] | null;
964
+ }, options?: ListingVisualHighlightsOptions): string[];
704
965
 
705
966
  /**
706
967
  * Market-data types for the public site.
@@ -973,4 +1234,4 @@ declare function resolveMatchedCoverPhoto(photo: MatchedListingPhoto | null | un
973
1234
  */
974
1235
  declare function applyMatchedPhotoCover<T extends Listing>(cards: ReadonlyArray<T>, photoResults: PhotoSearchResult | ReadonlyArray<PhotoSearchItem> | null | undefined, options?: ApplyMatchedPhotoCoverOptions): Array<T & ListingWithMatchedPhoto>;
975
1236
 
976
- export { AMENITY_FALLBACK_LABELS, type AmenityLabelDictionary, type AmenityLabelOption, AppliedSearchChange, AppliedSearchQuery, type ApplyMatchedPhotoCoverOptions, CmsCollection, CmsEntriesResult, CmsEntry, type ContactLeadInput, type CreateGaragemClientOptions, DEFAULT_PHONE_COUNTRY_CODE, FetchLike, type GaragemClient, type GetLeadUiOptions, type GetListingMarketPositionOptions, type GetNeighborhoodSummaryOptions, type HHmm, LISTING_AMENITY_TITLES, LISTING_DESCRIPTION_CLAMP, type LeadContact, type LeadField, type LeadFieldId, LeadSubmitError, type LeadSubmitErrorCode, type LeadSubmitResult, type LeadUi, Listing, type ListingAmenityGroup, type ListingAmenityGroupKey, type ListingAmenitySource, type ListingBreadcrumbCrumb, ListingBusinessType, type ListingCardModel, type ListingDescriptionPreview, ListingDetail, type ListingDetailFieldsModel, type ListingDetailFieldsSource, type ListingDetailModel, type ListingFact, ListingFilters, ListingLocation, type ListingLocationBlock, type ListingMarketPosition, ListingMedia, type ListingMediaOverlay, ListingPriceVisibility, type ListingValue, ListingWithMatchedPhoto, ListingsResult, type LocationFilterInput, MATCHED_PHOTO_COVER_MAX_DISTANCE, MAX_NATIONAL_PHONE_DIGITS, type MarketListingType, type MarketPriceBand, type MarketPropertyType, type MarketUnavailableReason, MatchedListingPhoto, type NeighborhoodSummary, type NeighborhoodSummaryQuery, PHONE_COUNTRIES, PHOTO_SEARCH_MIN_QUERY_LENGTH, type ParsedPhoneInput, type PhoneCountry, PhotoSearchItem, PhotoSearchParams, PhotoSearchResult, type PriceEstimate, type PriceEstimateConfidence, type PriceEstimateInput, QueryListingsFilters, QueryListingsParams, QueryListingsResult, RequestNextOptions, type RequestPriceEstimateOptions, type ResolvePublicSiteIdOptions, STUDIO_DEFAULT_VISIT_SCHEDULE, STUDIO_SDK_CONTRACT, STUDIO_SDK_PACKAGE, STUDIO_SITE_LAYOUT, type SearchListingPhotosOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, SimilarListingsResult, Site, type StudioSdkContract, VISIT_TIME_ZONE, type VisitHours, type VisitLeadInput, type VisitSchedule, type VisitScheduleConfig, applyMatchedPhotoCover, coerceNpmVersion, collapseDuplicatedBrazilianMobileNine, compareSemver, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, defaultPhoneCountry, expandVisitSchedule, expandVisitTimeSlots, findPhoneCountry, formatAreaM2, formatGroupedInteger, formatListingPrice, formatPhoneNational, getLeadUi, getListingMarketPosition, getNeighborhoodSummary, hasShowcaseLeadsPostUrl, isPhotoSearchOnPin, isStudioPreviewHost, isValidPhone, isVisitSlotAllowed, labelAmenities, listingAmenityGroups, listingBreadcrumb, listingBusinessLabel, listingDescriptionPreview, listingDetailFieldsModel, listingDetailModel, listingFacts, listingLocationBlock, listingLocationLabel, listingLookupKey, listingMapsHref, listingMediaOverlays, listingPublicPath, listingValues, marketExportsAvailableAt, marketPositionLabel, mergeAppliedSearchQueryIntoSearch, nationalPhoneDigits, normalizeVisitDate, normalizeVisitTime, parseAppliedSearchQuery, parseGroupedInteger, parsePhoneInput, parseReactSdkNamedImports, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, phoneCountrySearchValue, photoSearchUrl, priceBandLabel, reduceAppliedSearchQuery, remaskPhoneForCountry, requestPriceEstimate, resolveMatchedCoverPhoto, resolvePublicSiteId, searchListingPhotos, serializeAppliedSearchQuery, slotsForDate, studioAmenityInstruction, studioChromeInstruction, studioCodegenContractViolations, studioDefaultLeadUi, studioLayoutInstruction, studioLeadInstruction, studioListingCardInstruction, studioListingDetailInstruction, studioMarketInstruction, studioPhotoSearchInstruction, studioSdkPinInstruction, studioSearchInstruction, studioSearchLandmarkInstruction, studioSiteWidthCss, submitContactLead, submitVisitLead, toE164, toListingCardModel, truncateNationalPhoneDigits, unavailableReactImports };
1237
+ export { AMENITY_FALLBACK_LABELS, type AmenityLabelDictionary, type AmenityLabelOption, AppliedSearchChange, AppliedSearchQuery, type ApplyMatchedPhotoCoverOptions, BoundaryCity, BoundaryLayer, BoundaryLayerOptions, CmsCollection, CmsEntriesResult, CmsEntry, type ContactLeadInput, type CreateGaragemClientOptions, DEFAULT_MAPS_BASE_URL, DEFAULT_PHONE_COUNTRY_CODE, FetchLike, type GaragemClient, type GetLeadUiOptions, type GetListingMarketPositionOptions, type GetNeighborhoodSummaryOptions, type GetSimilarByPhotoOptions, type HHmm, LISTING_AMENITY_TITLES, LISTING_DESCRIPTION_CLAMP, type LeadContact, type LeadField, type LeadFieldId, LeadSubmitError, type LeadSubmitErrorCode, type LeadSubmitResult, type LeadUi, Listing, type ListingAmenityGroup, type ListingAmenityGroupKey, type ListingAmenitySource, type ListingBreadcrumbCrumb, type ListingDescriptionPreview, ListingDetail, type ListingDetailFieldsModel, type ListingDetailFieldsSource, type ListingDetailModel, type ListingFact, ListingFilters, ListingLocation, type ListingLocationBlock, type ListingMarketPosition, ListingMedia, type ListingMediaOverlay, type ListingPhotoGroup, type ListingValue, type ListingVisualHighlightsOptions, ListingWithLocation, ListingWithMatchedPhoto, ListingsResult, type LocationFilterInput, MAPS_MAX_IMAGE_EDGE, MAPS_SITE_HEADER, MATCHED_PHOTO_COVER_MAX_DISTANCE, MAX_NATIONAL_PHONE_DIGITS, MapsCoordinates, MapsFetchOptions, type MarketListingType, type MarketPriceBand, type MarketPropertyType, type MarketUnavailableReason, MatchedListingPhoto, NeighborhoodBoundary, NeighborhoodBoundaryOptions, type NeighborhoodSummary, type NeighborhoodSummaryQuery, PHONE_COUNTRIES, PHOTO_GROUP_OTHER_KEY, PHOTO_GROUP_OTHER_LABEL, PHOTO_SEARCH_MIN_QUERY_LENGTH, type ParsedPhoneInput, type PhoneCountry, PhotoSearchItem, PhotoSearchParams, PhotoSearchResult, type PriceEstimate, type PriceEstimateConfidence, type PriceEstimateInput, QueryListingsFilters, QueryListingsParams, QueryListingsResult, RequestNextOptions, type RequestPriceEstimateOptions, type ResolvePublicSiteIdOptions, STUDIO_DEFAULT_VISIT_SCHEDULE, STUDIO_SDK_CONTRACT, STUDIO_SDK_PACKAGE, STUDIO_SITE_LAYOUT, type SearchListingPhotosOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, type SimilarByPhotoItem, type SimilarByPhotoResult, SimilarListingsResult, type SimilarPhotoMatch, Site, StaticMapOptions, StreetViewAvailability, StreetViewAvailabilityOptions, StreetViewOptions, type StudioSdkContract, TravelDestination, TravelMode, TravelTime, TravelTimeCache, TravelTimeCacheOptions, TravelTimeElement, TravelTimeOptions, TravelTimesOptions, VISIT_TIME_ZONE, type VisitHours, type VisitLeadInput, type VisitSchedule, type VisitScheduleConfig, applyMatchedPhotoCover, boundaryCitySlug, boundaryLayerId, boundaryLayerUrl, clearTravelTimeCache, coarsenCoordinates, coerceNpmVersion, collapseDuplicatedBrazilianMobileNine, compareSemver, composeSearchPublicHref, composeSearchPublicPath, coordinateDecimals, createClient, createGaragemClient, createTravelTimeCache, defaultPhoneCountry, expandVisitSchedule, expandVisitTimeSlots, findPhoneCountry, formatAreaM2, formatGroupedInteger, formatListingPrice, formatPhoneNational, getBoundaryLayer, getLeadUi, getListingMarketPosition, getNeighborhoodSummary, getSimilarByPhoto, hasShowcaseLeadsPostUrl, isPhotoSearchOnPin, isStudioPreviewHost, isValidPhone, isVisitSlotAllowed, labelAmenities, listingAmenityGroups, listingBreadcrumb, listingBusinessLabel, listingCoordinates, listingDescriptionPreview, listingDetailFieldsModel, listingDetailModel, listingFacts, listingLocationBlock, listingLookupKey, listingMapsHref, listingMediaOverlays, listingPhotoGroups, listingPublicPath, listingStaticMapUrl, listingStreetViewAvailable, listingStreetViewMetadataUrl, listingStreetViewUrl, listingValues, listingVisualHighlights, mapsExportsPublished, marketExportsAvailableAt, marketPositionLabel, maxZoomForCoordinates, mergeAppliedSearchQueryIntoSearch, nationalPhoneDigits, neighborhoodBoundaryLayer, neighborhoodBoundaryUrl, normalizeMapsBaseUrl, normalizeVisitDate, normalizeVisitTime, parseAppliedSearchQuery, parseGroupedInteger, parsePhoneInput, parseReactSdkNamedImports, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, phoneCountrySearchValue, photoRoomLabel, photoSearchUrl, priceBandLabel, reduceAppliedSearchQuery, remaskPhoneForCountry, requestPriceEstimate, resolveMatchedCoverPhoto, resolvePublicSiteId, resolveTravelDestination, searchListingPhotos, serializeAppliedSearchQuery, slotsForDate, studioAmenityInstruction, studioChromeInstruction, studioCodegenContractViolations, studioDefaultLeadUi, studioLayoutInstruction, studioLeadInstruction, studioListingCardInstruction, studioListingDetailInstruction, studioMapsInstruction, studioMarketInstruction, studioPhotoInstruction, studioPhotoInstructionFor, studioPhotoSearchInstruction, studioPublishableKeyInstruction, studioSdkPinInstruction, studioSearchInstruction, studioSearchLandmarkInstruction, studioSiteWidthCss, submitContactLead, submitVisitLead, toE164, travelTimeCacheKey, travelTimeFromListing, travelTimesFromListing, truncateNationalPhoneDigits, unavailableReactImports };