@garagem-ai/site-sdk 0.8.0 → 0.9.1

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/README.md CHANGED
@@ -379,6 +379,156 @@ Works wherever `fetch` is available:
379
379
  - Edge runtime (Vercel Edge, Cloudflare Workers, Deno)
380
380
  - Browsers (use carefully — see "Public keys" below)
381
381
 
382
+ ## Maps (static map, street view, boundaries, travel time)
383
+
384
+ Helpers for `maps.fndn.ai`, the Garagem maps façade. They only use the
385
+ coordinates the public API already returns for a listing — those are
386
+ masked per site (≈100 m by default) and the helpers **never add precision**
387
+ (`maxDecimals` can only coarsen further). Pass `siteId` so usage is metered
388
+ per site on `maps.fndn.ai` (it is a label, not auth).
389
+
390
+ ```ts
391
+ import {
392
+ listingStaticMapUrl,
393
+ listingStreetViewAvailable,
394
+ listingStreetViewUrl,
395
+ } from "@garagem-ai/site-sdk";
396
+
397
+ const listing = await getListing({ siteId, listingId });
398
+
399
+ // <img src={...}> — zoom is capped by the coordinate precision (16 for the
400
+ // default ≈100 m mask), so the pin never pretends to know the exact door.
401
+ const map = listingStaticMapUrl(listing, {
402
+ width: 640,
403
+ height: 320,
404
+ zoom: 15,
405
+ style: "roadmap",
406
+ siteId,
407
+ });
408
+
409
+ // Metadata is free on Google's side; the image is billed. Check first.
410
+ const sv = await listingStreetViewAvailable(listing, { siteId });
411
+ const street = sv.available
412
+ ? listingStreetViewUrl(listing, { width: 640, height: 400, siteId })
413
+ : null;
414
+ ```
415
+
416
+ ### Neighbourhood outline on an interactive map
417
+
418
+ `boundaryLayerUrl(city)` returns the TileJSON for a city's boundary layer
419
+ (`sao_paulo`, `rio_de_janeiro`; other cities fall back to OSM data via
420
+ `source: "osm"`). `neighborhoodBoundaryLayer(city, name)` resolves one
421
+ outline as GeoJSON. With the Maps JS loader (`https://maps.fndn.ai/sdk.js`,
422
+ which injects the browser key for you — never ship your own Google key):
423
+
424
+ ```tsx
425
+ import { neighborhoodBoundaryLayer } from "@garagem-ai/site-sdk";
426
+
427
+ // <script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />
428
+ window.initMap = async () => {
429
+ const map = new google.maps.Map(el, { center, zoom: 14 });
430
+ const outline = await neighborhoodBoundaryLayer(
431
+ "São Paulo",
432
+ "Vila Madalena",
433
+ {
434
+ siteId,
435
+ }
436
+ );
437
+ if (outline.feature) {
438
+ map.data.addGeoJson(outline.feature);
439
+ map.data.setStyle({ fillOpacity: 0.08, strokeWeight: 2 });
440
+ }
441
+ };
442
+ ```
443
+
444
+ With MapLibre, use the vector tiles instead of GeoJSON for the whole city:
445
+
446
+ ```ts
447
+ map.addSource("sp", { type: "vector", url: boundaryLayerUrl("sao_paulo") });
448
+ map.addLayer({
449
+ id: "districts",
450
+ type: "line",
451
+ source: "sp",
452
+ "source-layer": "district", // see getBoundaryLayer(city).sourceLayers
453
+ });
454
+ ```
455
+
456
+ ### Travel time
457
+
458
+ ```ts
459
+ import { travelTimeFromListing } from "@garagem-ai/site-sdk";
460
+
461
+ const t = await travelTimeFromListing(listing, "Av. Paulista, 1000", {
462
+ mode: "transit", // driving (default) | walking | bicycling | transit
463
+ siteId,
464
+ });
465
+ // t → { minutes: 19, distanceKm: 5.2, cached: false, … } | null
466
+ ```
467
+
468
+ **Cost:** each uncached call is one Google Directions request on the shared
469
+ key (≈US$5 per 1 000 at list price; a free-text destination adds a
470
+ Nominatim geocode, which is free). Results are cached in-process for 15
471
+ minutes (200 entries, LRU) keyed by origin + destination + mode; pass
472
+ `cache: null` to opt out or `createTravelTimeCache({ ttlMs, maxEntries })`
473
+ to tune it. `travelTimesFromListing(listing, [...])` fans out to the Route
474
+ Matrix (≈US$5 per 1 000 elements, driving only, no distance). Call these
475
+ from a server component or route handler, not per card render.
476
+
477
+ ### Map search
478
+
479
+ Viewport and drawn-area search go through the friendly listings route
480
+ (`POST /api/sites/{siteId}/search/listings`). The SDK sends `bounds` or
481
+ `polygon` as numbers. The server builds one allowlisted
482
+ `coordinates:(lat,lng,…)` filter (the public index field — a rectangle is
483
+ the same clockwise polygon Foundation's map uses). Callers never send a
484
+ raw Typesense filter. A drawn polygon wins over the viewport.
485
+
486
+ ```ts
487
+ import {
488
+ searchListingsInBounds,
489
+ searchListingsInPolygon,
490
+ clusterPins,
491
+ } from "@garagem-ai/site-sdk";
492
+
493
+ const area = await searchListingsInBounds(siteId, {
494
+ bounds: { north: -23.5, south: -23.6, east: -46.6, west: -46.7 },
495
+ zoom: 14, // clustering hint only — not sent to the server
496
+ q: "varanda",
497
+ sort: "preco-asc",
498
+ location: { type: "neighborhood", value: "pinheiros" },
499
+ filters: { listing_type: "sale" },
500
+ publishableKey: "pk_live_…",
501
+ pageSize: 100, // capped at 100, the friendly-route maximum
502
+ });
503
+ // area.pins → { id, lat, lng, price, coverImage }[]
504
+ // area.cards → listing card models for the same page
505
+
506
+ const drawn = await searchListingsInPolygon(siteId, {
507
+ polygon: [
508
+ [-23.5, -46.7],
509
+ [-23.5, -46.6],
510
+ [-23.6, -46.6],
511
+ ], // [lat, lng], not GeoJSON [lng, lat]
512
+ filters: { listing_type: "sale" },
513
+ });
514
+
515
+ const clusters = clusterPins(area.pins, 14);
516
+ ```
517
+
518
+ Pins copy `listing.location.coordinates` exactly as the API returned them.
519
+ Those coordinates are already masked (≈100 m by default). Do not geocode
520
+ the street to sharpen a pin, and do not add decimals. `clusterPins` keeps
521
+ a lone pin's coordinates and rounds a group centroid back to the coarsest
522
+ pin in the cell. `pageSize` above 100 is clamped. A rectangle that crosses
523
+ the antimeridian (`east <= west`) is rejected.
524
+
525
+ `useMapSearch` (from `@garagem-ai/site-sdk/react`) debounces viewport
526
+ changes by 400ms — the same pause as Foundation's `/imoveis` map — aborts
527
+ the previous request, and returns `{ pins, cards, clusters }`. Changing
528
+ zoom only reclusters. **Every viewport change is a search call.** Do not
529
+ fire one per mousemove, do not raise the page size, and do not call travel
530
+ time or Street View from that loop.
531
+
382
532
  ## Publishable keys & rate limits
383
533
 
384
534
  Calls to `/api/sites/{siteId}/*` stay anonymous when you pass no key. A
@@ -399,8 +549,12 @@ export const garagem = createClient({
399
549
  `createClient` is an alias of `createGaragemClient`. The same
400
550
  `publishableKey` option exists on every fetcher (`getListings`,
401
551
  `getListing`, `getSite`, `getSearchUi`, `queryListings`, `searchListings`,
402
- the CMS helpers, `getLeadUi`, `submitVisitLead`, `submitContactLead`) and
403
- on `usePublicSearch`. The SDK sends it as `X-Garagem-Publishable-Key`.
552
+ the CMS helpers, `getLeadUi`, `submitVisitLead`, `submitContactLead`),
553
+ on `usePublicSearch`, and on map search (`searchListingsInBounds`,
554
+ `searchListingsInPolygon`, `useMapSearch`). The SDK sends it as
555
+ `X-Garagem-Publishable-Key`. A viewport search that omits the key spends
556
+ the anonymous listings budget. Pass the same `q`, `sort`, and `location`
557
+ as the list, or the pins will not match the active query.
404
558
  `Authorization: Bearer pk_live_…` is accepted too. A blank value is treated
405
559
  as no key.
406
560
 
@@ -443,11 +597,13 @@ to skip metering. Key and origin checks still run in both modes.
443
597
  Headless URL/search helpers live on the main entry (`readPublicSearch`,
444
598
  `hrefForPathFilters`, `toListingCardModel`, …). The React adapter is a
445
599
  separate subpath — peer `react` + `next` — and exports `usePublicSearch`
446
- only. Card, skeleton, and search chrome markup belong in the app.
600
+ and `useMapSearch`. Card, skeleton, and search chrome markup belong in the app.
447
601
 
448
602
  Studio codegen follows `STUDIO_SDK_CONTRACT`: pin
449
603
  `@garagem-ai/site-sdk` to `minNpmVersion` and import only
450
- `reactExports` (`usePublicSearch`). Do **not** import npm CSS
604
+ `reactExports` (`usePublicSearch`). `useMapSearch` is for hand-written
605
+ sites today; Studio prompts name it only once the pin reaches `mapsSince`
606
+ (0.7.0), together with the other maps helpers. Do **not** import npm CSS
451
607
  (`@garagem-ai/site-sdk/react/search.css`).
452
608
 
453
609
  ```tsx
@@ -519,7 +675,8 @@ resolve locally and do not hit the API.
519
675
  ## What's NOT in this release
520
676
 
521
677
  - CMS writes / drafts (editor + CMS worker only).
522
- - Typesense / InstantSearch helpers.
678
+ - Raw Typesense / InstantSearch adapters. Map viewport search uses the
679
+ friendly listings route described above.
523
680
  - LiveSession / lead submission helpers.
524
681
 
525
682
  All of these will land additively; the v0.2 surface above will not break.
package/dist/index.d.mts 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-CmGRj6my.mjs';
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-CmGRj6my.mjs';
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-DIoV75SN.mjs';
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-DIoV75SN.mjs';
3
3
 
4
4
  /**
5
5
  * Visit-lead schedule: hours in, slots out. Pure — no fetch, no React.
@@ -279,46 +279,6 @@ type ListingDetailFieldsSource = ListingAmenitySource & Pick<ListingDetail, "pri
279
279
  */
280
280
  declare function listingDetailFieldsModel(listing: ListingDetailFieldsSource, dictionary?: AmenityLabelDictionary): ListingDetailFieldsModel;
281
281
 
282
- /** Fields every listing card must have — no JSX. */
283
- type ListingCardModel = {
284
- href: string;
285
- title: string;
286
- businessType: ListingBusinessType;
287
- businessLabel: string;
288
- priceVisibility: ListingPriceVisibility;
289
- price: number | null;
290
- priceLabel: string;
291
- pricePeriod: string | null;
292
- locationLabel: string;
293
- propertyType: string | null;
294
- coverSrc: string | null;
295
- coverAlt: string;
296
- bedrooms: number | null;
297
- bathrooms: number | null;
298
- parkingSpaces: number | null;
299
- areaM2: number | null;
300
- };
301
- declare function listingLocationLabel(location: {
302
- neighborhood?: string | null;
303
- city?: string | null;
304
- state?: string | null;
305
- }): string;
306
- declare function toListingCardModel(listing: Pick<Listing, "id" | "listingCode" | "path" | "title" | "businessType" | "price" | "currency" | "priceVisibility" | "coverImage"> & {
307
- property?: {
308
- type?: string | null;
309
- bedrooms?: number | null;
310
- bathrooms?: number | null;
311
- parkingSpaces?: number | null;
312
- usableArea?: number | null;
313
- totalArea?: number | null;
314
- };
315
- location?: {
316
- neighborhood?: string | null;
317
- city?: string | null;
318
- state?: string | null;
319
- };
320
- }): ListingCardModel;
321
-
322
282
  /**
323
283
  * Presentation helpers with no UI framework.
324
284
  * Adapters consume these formatters; they must not live inside JSX.
@@ -468,11 +428,13 @@ declare const STUDIO_SDK_CONTRACT: {
468
428
  * this and move that release's names from `optionalReactExports` /
469
429
  * `unpublishedSearchExports` / `unpublishedPhoneExports` into the
470
430
  * prompt-safe lists. Do not bump here until that tarball is on npm.
471
- * Phone mask helpers shipped in 0.6.0. Search filter helpers
431
+ * Phone mask helpers shipped in 0.6.0. Map search
432
+ * (`useMapSearch`, `searchListingsInBounds`) shipped in 0.9.0 — 0.7.0
433
+ * does not export them. Search filter helpers
472
434
  * (`visibleSearchFilters` / `toolbarFilterIds`) shipped in 0.4.12 and
473
435
  * remain on this pin.
474
436
  */
475
- readonly minNpmVersion: "0.6.0";
437
+ readonly minNpmVersion: "0.9.0";
476
438
  /** Historical: older tarballs inject card CSS when those components mount. */
477
439
  readonly selfInjectSince: "0.4.2";
478
440
  readonly chromeStrategy: "app-owned";
@@ -542,6 +504,18 @@ declare const STUDIO_SDK_CONTRACT: {
542
504
  * already listed in `searchExports`.
543
505
  */
544
506
  readonly unpublishedSearchExports: readonly ["searchChromeModel", "rangeDraftFromPath"];
507
+ /**
508
+ * maps.fndn.ai helpers (static map, street view, boundaries, travel
509
+ * time) plus friendly map search. They ship in npm 0.9.0 (`mapsSince`).
510
+ * Listing-detail map guidance stays empty: `studioMapsInstruction()`
511
+ * keeps the listing contract for a later task and Studio does not
512
+ * inject it. Map search is `studioMapSearchInstruction()`, and only
513
+ * the site that opted into list-and-map may include that text.
514
+ * `useMapSearch` is a `/react` hook in `optionalReactExports`; the
515
+ * pin sentence does not name it.
516
+ */
517
+ readonly mapsSince: "0.9.0";
518
+ readonly mapsExports: readonly ["listingStaticMapUrl", "listingStreetViewUrl", "listingStreetViewAvailable", "neighborhoodBoundaryLayer", "boundaryLayerUrl", "travelTimeFromListing", "searchListingsInBounds", "searchListingsInPolygon", "clusterPins"];
545
519
  /**
546
520
  * Market-data helpers (neighborhood price summary, listing market
547
521
  * position, visitor price estimate, pt-BR labels). They ship in
@@ -615,6 +589,23 @@ declare function studioPhotoInstructionFor(published: readonly string[]): string
615
589
  declare function studioPhotoInstruction(): string;
616
590
  declare function studioAmenityInstruction(): string;
617
591
  declare function studioSearchInstruction(): string;
592
+ /** Whether the Studio pin already carries the maps helpers. */
593
+ declare function mapsExportsPublished(pin?: string): boolean;
594
+ /**
595
+ * Listing-detail maps guidance. Empty while the pinned tarball predates
596
+ * `mapsSince`, because v0 copies every identifier it reads and the preview
597
+ * ESM loader throws on a missing named export.
598
+ */
599
+ declare function studioMapsInstruction(options?: {
600
+ pin?: string;
601
+ }): string;
602
+ /**
603
+ * Search-page map mode. Empty below `mapsSince`. Studio injects this only
604
+ * when the site chose list and map. Listing-detail helpers stay out of it.
605
+ */
606
+ declare function studioMapSearchInstruction(options?: {
607
+ pin?: string;
608
+ }): string;
618
609
  /** True when the pinned tarball ships the market-data helpers. */
619
610
  declare function marketExportsAvailableAt(pin: string): boolean;
620
611
  /**
@@ -755,6 +746,112 @@ declare function createGaragemClient(options?: CreateGaragemClientOptions): Gara
755
746
  */
756
747
  declare const createClient: typeof createGaragemClient;
757
748
 
749
+ /**
750
+ * maps.fndn.ai helpers: static map / street view image URLs, boundary
751
+ * layers for MapLibre, and travel time. All of them consume the coordinates
752
+ * the public listings API already masked for the site — nothing here calls
753
+ * Google directly or adds precision.
754
+ *
755
+ * URL shapes mirror `@garagem/geo` (`buildGoogleStaticMapImageUrl`,
756
+ * `buildStreetViewImageUrl`); the SDK keeps its own copy because the
757
+ * published package cannot bundle the private geo workspace package. A
758
+ * parity test in `tests/maps-geo-parity.test.ts` keeps the two in sync.
759
+ */
760
+
761
+ declare const DEFAULT_MAPS_BASE_URL = "https://maps.fndn.ai";
762
+ /** Header maps.fndn.ai meters per site. Mirrors `apps/maps` `SITE_HEADER`. */
763
+ declare const MAPS_SITE_HEADER = "X-Garagem-Site";
764
+ /** Google Static Maps / Street View Static edge ceiling. */
765
+ declare const MAPS_MAX_IMAGE_EDGE = 640;
766
+ /**
767
+ * Coordinates the public API returned for a listing, or `null` when the
768
+ * listing has none (or a `0,0` placeholder). Values are passed through
769
+ * untouched — they are already masked per the site's precision setting.
770
+ */
771
+ declare function listingCoordinates(listing: ListingWithLocation): MapsCoordinates | null;
772
+ /** Number of decimal places carried by a coordinate (`-23.55` → 2). */
773
+ declare function coordinateDecimals(value: number): number;
774
+ /**
775
+ * Reduce coordinates to at most `maxDecimals` places. Never adds precision:
776
+ * a point the API already masked to 3 decimals stays at 3 when asked for 6.
777
+ */
778
+ declare function coarsenCoordinates(coordinates: MapsCoordinates, maxDecimals: number | undefined): MapsCoordinates;
779
+ /**
780
+ * Highest zoom that does not overstate the precision of the coordinates.
781
+ * 3 decimals (≈100 m, the public default) caps at 16; 2 (≈1 km) at 13;
782
+ * 1 or fewer at 11; 4+ decimals get the full Google range (21).
783
+ */
784
+ declare function maxZoomForCoordinates(coordinates: MapsCoordinates): number;
785
+ declare function normalizeMapsBaseUrl(baseUrl: string | undefined): string;
786
+ /**
787
+ * `GET /v1/static-map` URL for an `<img>`. Returns `null` when the listing
788
+ * has no public coordinates. Zoom is capped by the coordinate precision.
789
+ */
790
+ declare function listingStaticMapUrl(listing: ListingWithLocation, options?: StaticMapOptions): string | null;
791
+ /**
792
+ * `GET /v1/street-view` URL for an `<img>`. Returns `null` when the listing
793
+ * has no public coordinates. Google picks the nearest panorama to the
794
+ * (masked) point, so pair it with `listingStreetViewAvailable`.
795
+ */
796
+ declare function listingStreetViewUrl(listing: ListingWithLocation, options?: StreetViewOptions): string | null;
797
+ /** `GET /v1/street-view/metadata` URL (free on Google's side). */
798
+ declare function listingStreetViewMetadataUrl(listing: ListingWithLocation, options?: StreetViewAvailabilityOptions): string | null;
799
+ /**
800
+ * Whether Google has a panorama near the listing. Metadata lookups are free,
801
+ * so call this before rendering `listingStreetViewUrl` (which is billed).
802
+ * Network failures resolve to `{ available: false, status: "ERROR" }`.
803
+ */
804
+ declare function listingStreetViewAvailable(listing: ListingWithLocation, options?: StreetViewAvailabilityOptions): Promise<StreetViewAvailability>;
805
+ /** `"São Paulo"` → `sao_paulo`; existing slugs pass through. */
806
+ declare function boundaryCitySlug(city: string): string;
807
+ /** maps.fndn.ai layer id for a city's boundaries (`sao_paulo_boundaries`). */
808
+ declare function boundaryLayerId(city: BoundaryCity): string;
809
+ /**
810
+ * URL for a city's boundary layer. `kind` picks the representation:
811
+ * `tilejson` (default) for MapLibre vector sources, `tiles` for the raw
812
+ * `{z}/{x}/{y}` template, `geojson` for the whole city, `layer` for the
813
+ * descriptor served by `/v1/layers/:id`.
814
+ */
815
+ declare function boundaryLayerUrl(city: BoundaryCity, options?: BoundaryLayerOptions): string;
816
+ /** GeoJSON URL for one named outline (`/api/boundaries/:city/:name`). */
817
+ declare function neighborhoodBoundaryUrl(city: BoundaryCity, neighborhood: string, options?: NeighborhoodBoundaryOptions): string;
818
+ /** Fetch the layer descriptor (`/v1/layers/:id`). `null` when unknown. */
819
+ declare function getBoundaryLayer(city: BoundaryCity, options?: MapsFetchOptions): Promise<BoundaryLayer | null>;
820
+ /**
821
+ * Resolve a neighbourhood outline so a site map can draw it. maps.fndn.ai
822
+ * matches the name case-insensitively: an exact match returns one feature,
823
+ * a partial match may return several (`candidates`), none returns
824
+ * `feature: null`.
825
+ */
826
+ declare function neighborhoodBoundaryLayer(city: BoundaryCity, neighborhood: string, options?: NeighborhoodBoundaryOptions): Promise<NeighborhoodBoundary>;
827
+ /** Small LRU with TTL. Lives per module instance (one per page/worker). */
828
+ declare function createTravelTimeCache(options?: TravelTimeCacheOptions): TravelTimeCache;
829
+ /** Drop every cached travel time (tests, or after a listing moves). */
830
+ declare function clearTravelTimeCache(): void;
831
+ declare function travelTimeCacheKey(origin: MapsCoordinates, destination: MapsCoordinates, mode: TravelMode): string;
832
+ /**
833
+ * Resolve a free-text destination through `/v1/geocode` (Nominatim first,
834
+ * so usually free). Coordinates pass through.
835
+ */
836
+ declare function resolveTravelDestination(destination: TravelDestination, options?: MapsFetchOptions): Promise<MapsCoordinates | null>;
837
+ /**
838
+ * Travel time from the listing's (masked) coordinates to a destination via
839
+ * `GET /v1/directions`. Each uncached call is one Google Directions request
840
+ * on the shared key (≈US$5 per 1 000 at list price, metered per site when
841
+ * `siteId` is set). Cache hits are free, including the geocode a string
842
+ * destination would otherwise spend. Returns `null` when the listing has no
843
+ * coordinates, the destination cannot be resolved, or no route exists.
844
+ */
845
+ declare function travelTimeFromListing(listing: ListingWithLocation, destination: TravelDestination, options?: TravelTimeOptions): Promise<TravelTime | null>;
846
+ /**
847
+ * Driving time from the listing to many destinations in one
848
+ * `POST /v1/route-matrix` call (Google Route Matrix, billed per element:
849
+ * ≈US$5 per 1 000 at list price). Distances are not returned by the matrix.
850
+ * Element is `null` when Google found no route; the whole result is `null`
851
+ * when the listing has no coordinates or the request failed.
852
+ */
853
+ declare function travelTimesFromListing(listing: ListingWithLocation, destinations: MapsCoordinates[], options?: TravelTimesOptions): Promise<Array<TravelTimeElement | null> | null>;
854
+
758
855
  /**
759
856
  * Photo intelligence types for the public Sites API.
760
857
  *
@@ -1147,4 +1244,4 @@ declare function resolveMatchedCoverPhoto(photo: MatchedListingPhoto | null | un
1147
1244
  */
1148
1245
  declare function applyMatchedPhotoCover<T extends Listing>(cards: ReadonlyArray<T>, photoResults: PhotoSearchResult | ReadonlyArray<PhotoSearchItem> | null | undefined, options?: ApplyMatchedPhotoCoverOptions): Array<T & ListingWithMatchedPhoto>;
1149
1246
 
1150
- 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 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, ListingBusinessType, type ListingCardModel, type ListingDescriptionPreview, ListingDetail, type ListingDetailFieldsModel, type ListingDetailFieldsSource, type ListingDetailModel, type ListingFact, ListingFilters, ListingLocation, type ListingLocationBlock, type ListingMarketPosition, ListingMedia, type ListingMediaOverlay, type ListingPhotoGroup, ListingPriceVisibility, type ListingValue, type ListingVisualHighlightsOptions, 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_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, type StudioSdkContract, VISIT_TIME_ZONE, type VisitHours, type VisitLeadInput, type VisitSchedule, type VisitScheduleConfig, applyMatchedPhotoCover, coerceNpmVersion, collapseDuplicatedBrazilianMobileNine, compareSemver, composeSearchPublicHref, composeSearchPublicPath, createClient, createGaragemClient, defaultPhoneCountry, expandVisitSchedule, expandVisitTimeSlots, findPhoneCountry, formatAreaM2, formatGroupedInteger, formatListingPrice, formatPhoneNational, getLeadUi, getListingMarketPosition, getNeighborhoodSummary, getSimilarByPhoto, hasShowcaseLeadsPostUrl, isPhotoSearchOnPin, isStudioPreviewHost, isValidPhone, isVisitSlotAllowed, labelAmenities, listingAmenityGroups, listingBreadcrumb, listingBusinessLabel, listingDescriptionPreview, listingDetailFieldsModel, listingDetailModel, listingFacts, listingLocationBlock, listingLocationLabel, listingLookupKey, listingMapsHref, listingMediaOverlays, listingPhotoGroups, listingPublicPath, listingValues, listingVisualHighlights, marketExportsAvailableAt, marketPositionLabel, mergeAppliedSearchQueryIntoSearch, nationalPhoneDigits, normalizeVisitDate, normalizeVisitTime, parseAppliedSearchQuery, parseGroupedInteger, parsePhoneInput, parseReactSdkNamedImports, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, phoneCountrySearchValue, photoRoomLabel, photoSearchUrl, priceBandLabel, reduceAppliedSearchQuery, remaskPhoneForCountry, requestPriceEstimate, resolveMatchedCoverPhoto, resolvePublicSiteId, searchListingPhotos, serializeAppliedSearchQuery, slotsForDate, studioAmenityInstruction, studioChromeInstruction, studioCodegenContractViolations, studioDefaultLeadUi, studioLayoutInstruction, studioLeadInstruction, studioListingCardInstruction, studioListingDetailInstruction, studioMarketInstruction, studioPhotoInstruction, studioPhotoInstructionFor, studioPhotoSearchInstruction, studioPublishableKeyInstruction, studioSdkPinInstruction, studioSearchInstruction, studioSearchLandmarkInstruction, studioSiteWidthCss, submitContactLead, submitVisitLead, toE164, toListingCardModel, truncateNationalPhoneDigits, unavailableReactImports };
1247
+ 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, studioMapSearchInstruction, studioMapsInstruction, studioMarketInstruction, studioPhotoInstruction, studioPhotoInstructionFor, studioPhotoSearchInstruction, studioPublishableKeyInstruction, studioSdkPinInstruction, studioSearchInstruction, studioSearchLandmarkInstruction, studioSiteWidthCss, submitContactLead, submitVisitLead, toE164, travelTimeCacheKey, travelTimeFromListing, travelTimesFromListing, truncateNationalPhoneDigits, unavailableReactImports };