@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/README.md +329 -31
- package/dist/index.d.mts +305 -44
- package/dist/index.d.ts +305 -44
- package/dist/index.js +1282 -34
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1233 -34
- package/dist/index.mjs.map +1 -1
- package/dist/react.d.mts +29 -2
- package/dist/react.d.ts +29 -2
- package/dist/react.js +639 -26
- package/dist/react.js.map +1 -1
- package/dist/react.mjs +638 -26
- package/dist/react.mjs.map +1 -1
- package/dist/{types-photo-search-OeONNDxl.d.mts → types-photo-search-D88oevZv.d.mts} +400 -1
- package/dist/{types-photo-search-OeONNDxl.d.ts → types-photo-search-D88oevZv.d.ts} +400 -1
- package/package.json +1 -1
- package/src/client.ts +23 -0
- package/src/fetchers-photos.ts +98 -0
- package/src/fetchers.ts +96 -30
- package/src/index.ts +120 -2
- package/src/internal/sdk-http.ts +122 -0
- package/src/leads.ts +34 -3
- package/src/listing-photos.ts +312 -0
- package/src/map-search.ts +487 -0
- package/src/maps.ts +743 -0
- package/src/react/index.ts +2 -0
- package/src/react/types.ts +5 -0
- package/src/react/use-map-search.ts +101 -0
- package/src/react/use-public-search.ts +23 -5
- package/src/resolve-site-id.ts +3 -0
- package/src/studio-contract.ts +120 -0
- package/src/types-maps.ts +275 -0
- package/src/types-photos.ts +46 -0
- package/src/types.ts +23 -0
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,
|
|
2
|
-
export {
|
|
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.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-D88oevZv.mjs';
|
|
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,
|
|
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 };
|