@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 +162 -5
- package/dist/index.d.mts +142 -45
- package/dist/index.d.ts +142 -45
- package/dist/index.js +758 -6
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +718 -6
- package/dist/index.mjs.map +1 -1
- package/dist/react.d.mts +24 -2
- package/dist/react.d.ts +24 -2
- package/dist/react.js +499 -12
- package/dist/react.js.map +1 -1
- package/dist/react.mjs +498 -12
- package/dist/react.mjs.map +1 -1
- package/dist/{types-photo-search-CmGRj6my.d.mts → types-photo-search-DIoV75SN.d.mts} +375 -1
- package/dist/{types-photo-search-CmGRj6my.d.ts → types-photo-search-DIoV75SN.d.ts} +375 -1
- package/package.json +2 -2
- package/src/fetchers.ts +4 -1
- package/src/index.ts +90 -0
- package/src/map-search.ts +491 -0
- package/src/maps.ts +743 -0
- package/src/react/index.ts +2 -0
- package/src/react/use-map-search.ts +101 -0
- package/src/studio-contract.ts +67 -3
- package/src/types-maps.ts +275 -0
- package/src/types.ts +12 -0
package/src/react/index.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
"use client";
|
|
2
2
|
|
|
3
3
|
export { usePublicSearch } from "./use-public-search";
|
|
4
|
+
export { useMapSearch } from "./use-map-search";
|
|
5
|
+
export type { UseMapSearchOptions, UseMapSearchResult } from "./use-map-search";
|
|
4
6
|
export type {
|
|
5
7
|
PublicSearchSnapshot,
|
|
6
8
|
PublicSearchState,
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
"use client";
|
|
2
|
+
|
|
3
|
+
import { useEffect, useMemo, useRef, useState } from "react";
|
|
4
|
+
|
|
5
|
+
import {
|
|
6
|
+
clusterPins,
|
|
7
|
+
emptyMapSearchResult,
|
|
8
|
+
MAP_VIEWPORT_DEBOUNCE_MS,
|
|
9
|
+
mapSearchSubscriptionKey,
|
|
10
|
+
subscribeMapSearch,
|
|
11
|
+
type MapSearchResult,
|
|
12
|
+
type MapSearchSubscription,
|
|
13
|
+
} from "../map-search";
|
|
14
|
+
import type { MapBounds, MapPinCluster, MapPolygon } from "../types-maps";
|
|
15
|
+
|
|
16
|
+
export interface UseMapSearchOptions extends Omit<
|
|
17
|
+
MapSearchSubscription,
|
|
18
|
+
"bounds" | "polygon"
|
|
19
|
+
> {
|
|
20
|
+
bounds?: MapBounds | null;
|
|
21
|
+
polygon?: MapPolygon | null;
|
|
22
|
+
/** Grid zoom for `clusterPins`. Changing it does not refetch. Default 14. */
|
|
23
|
+
zoom?: number;
|
|
24
|
+
/** Set false to keep the last result without fetching. */
|
|
25
|
+
enabled?: boolean;
|
|
26
|
+
/** Default 400, matching Foundation's map viewport debounce. */
|
|
27
|
+
debounceMs?: number;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export interface UseMapSearchResult extends MapSearchResult {
|
|
31
|
+
clusters: MapPinCluster[];
|
|
32
|
+
loading: boolean;
|
|
33
|
+
error: Error | null;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
const IDLE: MapSearchResult = emptyMapSearchResult();
|
|
37
|
+
|
|
38
|
+
function areaKey(options: UseMapSearchOptions): string {
|
|
39
|
+
return JSON.stringify({
|
|
40
|
+
search: mapSearchSubscriptionKey(options),
|
|
41
|
+
enabled: options.enabled !== false,
|
|
42
|
+
debounceMs: options.debounceMs ?? MAP_VIEWPORT_DEBOUNCE_MS,
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Search listings as the map moves. Debounces, aborts the previous request,
|
|
48
|
+
* and clusters the masked pins for the current zoom without another search.
|
|
49
|
+
* Disabling keeps the last result and settles `loading`: abort is not an event.
|
|
50
|
+
*/
|
|
51
|
+
export function useMapSearch(options: UseMapSearchOptions): UseMapSearchResult {
|
|
52
|
+
const [result, setResult] = useState<MapSearchResult>(IDLE);
|
|
53
|
+
const [loading, setLoading] = useState(false);
|
|
54
|
+
const [error, setError] = useState<Error | null>(null);
|
|
55
|
+
const optionsRef = useRef(options);
|
|
56
|
+
optionsRef.current = options;
|
|
57
|
+
const key = areaKey(options);
|
|
58
|
+
const zoom = options.zoom ?? 14;
|
|
59
|
+
|
|
60
|
+
useEffect(() => {
|
|
61
|
+
const current = optionsRef.current;
|
|
62
|
+
if (current.enabled === false) {
|
|
63
|
+
// The previous subscription's abort is ignored, and this effect does
|
|
64
|
+
// not start a replacement search, so nothing else can clear `loading`.
|
|
65
|
+
setLoading(false);
|
|
66
|
+
return;
|
|
67
|
+
}
|
|
68
|
+
return subscribeMapSearch(
|
|
69
|
+
current,
|
|
70
|
+
(event) => {
|
|
71
|
+
if (event.type === "empty") {
|
|
72
|
+
setResult(emptyMapSearchResult(current.pageSize));
|
|
73
|
+
setLoading(false);
|
|
74
|
+
setError(null);
|
|
75
|
+
return;
|
|
76
|
+
}
|
|
77
|
+
if (event.type === "loading") {
|
|
78
|
+
setLoading(true);
|
|
79
|
+
setError(null);
|
|
80
|
+
return;
|
|
81
|
+
}
|
|
82
|
+
if (event.type === "error") {
|
|
83
|
+
setLoading(false);
|
|
84
|
+
setError(event.error);
|
|
85
|
+
return;
|
|
86
|
+
}
|
|
87
|
+
setResult(event.result);
|
|
88
|
+
setLoading(false);
|
|
89
|
+
setError(null);
|
|
90
|
+
},
|
|
91
|
+
{ debounceMs: current.debounceMs }
|
|
92
|
+
);
|
|
93
|
+
}, [key]);
|
|
94
|
+
|
|
95
|
+
const clusters = useMemo(
|
|
96
|
+
() => clusterPins(result.pins, zoom),
|
|
97
|
+
[result.pins, zoom]
|
|
98
|
+
);
|
|
99
|
+
|
|
100
|
+
return { ...result, clusters, loading, error };
|
|
101
|
+
}
|
package/src/studio-contract.ts
CHANGED
|
@@ -20,11 +20,13 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
20
20
|
* this and move that release's names from `optionalReactExports` /
|
|
21
21
|
* `unpublishedSearchExports` / `unpublishedPhoneExports` into the
|
|
22
22
|
* prompt-safe lists. Do not bump here until that tarball is on npm.
|
|
23
|
-
* Phone mask helpers shipped in 0.6.0.
|
|
23
|
+
* Phone mask helpers shipped in 0.6.0. Map search
|
|
24
|
+
* (`useMapSearch`, `searchListingsInBounds`) shipped in 0.9.0 — 0.7.0
|
|
25
|
+
* does not export them. Search filter helpers
|
|
24
26
|
* (`visibleSearchFilters` / `toolbarFilterIds`) shipped in 0.4.12 and
|
|
25
27
|
* remain on this pin.
|
|
26
28
|
*/
|
|
27
|
-
minNpmVersion: "0.
|
|
29
|
+
minNpmVersion: "0.9.0",
|
|
28
30
|
/** Historical: older tarballs inject card CSS when those components mount. */
|
|
29
31
|
selfInjectSince: "0.4.2",
|
|
30
32
|
chromeStrategy: "app-owned" as const,
|
|
@@ -38,6 +40,7 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
38
40
|
*/
|
|
39
41
|
optionalReactExports: {
|
|
40
42
|
usePublicPhotoSearch: "0.7.0",
|
|
43
|
+
useMapSearch: "0.9.0",
|
|
41
44
|
} as Record<string, string>,
|
|
42
45
|
/**
|
|
43
46
|
* Former `/react` chrome (including card/skeleton inject). Completeness
|
|
@@ -146,6 +149,28 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
146
149
|
"searchChromeModel",
|
|
147
150
|
"rangeDraftFromPath",
|
|
148
151
|
] as const,
|
|
152
|
+
/**
|
|
153
|
+
* maps.fndn.ai helpers (static map, street view, boundaries, travel
|
|
154
|
+
* time) plus friendly map search. They ship in npm 0.9.0 (`mapsSince`).
|
|
155
|
+
* Listing-detail map guidance stays empty: `studioMapsInstruction()`
|
|
156
|
+
* keeps the listing contract for a later task and Studio does not
|
|
157
|
+
* inject it. Map search is `studioMapSearchInstruction()`, and only
|
|
158
|
+
* the site that opted into list-and-map may include that text.
|
|
159
|
+
* `useMapSearch` is a `/react` hook in `optionalReactExports`; the
|
|
160
|
+
* pin sentence does not name it.
|
|
161
|
+
*/
|
|
162
|
+
mapsSince: "0.9.0",
|
|
163
|
+
mapsExports: [
|
|
164
|
+
"listingStaticMapUrl",
|
|
165
|
+
"listingStreetViewUrl",
|
|
166
|
+
"listingStreetViewAvailable",
|
|
167
|
+
"neighborhoodBoundaryLayer",
|
|
168
|
+
"boundaryLayerUrl",
|
|
169
|
+
"travelTimeFromListing",
|
|
170
|
+
"searchListingsInBounds",
|
|
171
|
+
"searchListingsInPolygon",
|
|
172
|
+
"clusterPins",
|
|
173
|
+
] as const,
|
|
149
174
|
/**
|
|
150
175
|
* Market-data helpers (neighborhood price summary, listing market
|
|
151
176
|
* position, visitor price estimate, pt-BR labels). They ship in
|
|
@@ -306,7 +331,10 @@ export function studioPublishableKeyInstruction(): string {
|
|
|
306
331
|
|
|
307
332
|
export function studioSdkPinInstruction(): string {
|
|
308
333
|
const version = STUDIO_SDK_CONTRACT.minNpmVersion;
|
|
309
|
-
|
|
334
|
+
// Base hooks only. Optional hooks (`useMapSearch`, `usePublicPhotoSearch`)
|
|
335
|
+
// are named by the guidance that owns them, so a list-only site never
|
|
336
|
+
// sees the identifier.
|
|
337
|
+
const names = STUDIO_SDK_CONTRACT.reactExports.join(", ");
|
|
310
338
|
return `In \`package.json\` set \`"@garagem-ai/site-sdk": "${version}"\` (exact). Import only these \`${STUDIO_SDK_PACKAGE}/react\` names: ${names}.`;
|
|
311
339
|
}
|
|
312
340
|
|
|
@@ -371,6 +399,35 @@ export function studioSearchInstruction(): string {
|
|
|
371
399
|
return `Search: import ${reactNames} from \`${STUDIO_SDK_PACKAGE}/react\`. From \`${STUDIO_SDK_PACKAGE}\` import ${libNames}. Prefetch \`getSearchUi\` + \`queryListings\` on the server page. \`const search = usePublicSearch({ siteId, baseUrl: GARAGEM_API_BASE, search: searchFromServer, initial })\` where \`searchFromServer\` is \`new URLSearchParams(await searchParams).toString()\` — never shorthand \`{ search }\` beside \`const search =\` (temporal dead zone). Do not wrap this UI in \`<Suspense>\` and do not add a route \`loading\` file — heading and cards are ordinary elements in the document, visible with JavaScript off. Compose the page UI in the app — do not paste a canonical search TSX. Required chrome (design is free; omit none): query (\`qDraft\` / \`setQDraft\` / form \`preventDefault\` + \`submitQuery\`), heading (count span FIRST then h1 from \`searchResultsHeading(search.pathFilters, search.schema?.dictionary, search.locationNames)\` — never \`searchResultsHeading({})\`), toolbar (\`toolbarFilterIds\` + \`applyFilter\`; range “Atualizar” on that toolbar item only) vs sheet (\`visibleSearchFilters\` extras, \`stageFilter\`, one footer \`applyStaged\`), sort (\`searchSortOptions\` + \`setSort\`; first option id is \`""\` / “Mais relevantes” — map **only** that empty id to Select sentinel \`"relevancia"\` (\`opt.id || "relevancia"\`), never \`SelectItem value=""\` and never give “Mais recentes” (\`id: "recentes"\`, \`?ordenar=recentes\`) that sentinel; on change \`setSort(id === "relevancia" ? "" : id)\` so recentes stays recentes. Closed trigger shows the option \`.label\`, never \`{search.applied.sort}\`), grid (\`listings.map\` + the site listing-card module; listing-card-skeleton only for a slot whose content is still unknown, never as a Suspense fallback; do not \`throw\` in that chrome), pagination (\`paginationPages\` + \`hrefWithExplicitPage\`). Never interpolate \`schema\`, \`pathFilters\`, or a filter object as a React child. \`queryListings\` key is \`params\`. The URL is the document. Count text is \`{search.total}\` only. Heading is one row; font size lives on the container and the span and h1 use \`font-size: inherit\`. Sort trigger shows the option label (“Mais relevantes” when \`ordenar\` is absent), chevron at the end, same height as the toolbar controls. Toolbar ranges open a Popover form (not DropdownMenu — Menu typeahead swallows digit keys) whose submit calls \`applyFilter\`; the popup clips and the two inputs stay inside (\`min-w-0\`, no \`w-64\`). Reset min/max drafts when the popover opens and when the applied path range changes. The sheet omits toolbar ids (price, bedrooms) so Preço is never a heading without inputs. Sheet DialogContent uses \`h-[min(640px,85dvh)]\` (not max-h alone) so the body ScrollArea can move. Tipo de imóvel, características and comodidades each use a nested ScrollArea with \`h-56 overflow-hidden\` (viewport \`h-full\`). Area is two inputs in schema order with no “Aplicar”; the footer stages then applyStaged. Never read \`staged[filter.id]\` — path keys are \`bedrooms\` / \`listingType\` / \`bathrooms\`. Bedrooms Select reads \`pathFilters.bedrooms\` so \`/imoveis/4-quartos\` checks \`"4"\` and shows the same trigger dot as price. Bathrooms and parking pressed state uses \`pathFilterHasOption\`. Limpar keeps location plus toolbar price and bedrooms via \`clearStagedPathFilters\` and \`toolbarFilterIds\`; do not call \`clearStaged\` for that button. It enables only when staged has a path filter other than location and those kept toolbar ids. Each multi-select \`stageFilter\` value is one option id, never a concatenated slug; \`checked\` uses \`pathFilterHasOption\`. Listing type does not pass the clicked id: no path value shows every checkbox checked, unchecking one stages the other option's id, and the last box stays checked. Price inputs use formatGroupedInteger. The closed price and bedrooms triggers keep the filter label plus a dot when set — never the literal range. Empty price calls applyFilter(id, undefined); never send 0 or 1000000000. Area is a plain integer (not that mask). The results button stageFilter property_area_total with both drafts, then applyStaged. Never send 0 or 100000. Count buttons pass the option id (\`"2"\`), never the label \`"2+"\`. Property type, features, and amenities render in pt-BR label order. Do not set \`[data-slot="search-sort"] { flex-direction: column }\` in a \`<style>\` tag; that selector is row so the chevron sits beside the label. Empty copy: ${JSON.stringify(SEARCH_EMPTY_COPY)}`;
|
|
372
400
|
}
|
|
373
401
|
|
|
402
|
+
/** Whether the Studio pin already carries the maps helpers. */
|
|
403
|
+
export function mapsExportsPublished(
|
|
404
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
405
|
+
): boolean {
|
|
406
|
+
return compareSemver(pin, STUDIO_SDK_CONTRACT.mapsSince) >= 0;
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
/**
|
|
410
|
+
* Listing-detail maps guidance. Empty while the pinned tarball predates
|
|
411
|
+
* `mapsSince`, because v0 copies every identifier it reads and the preview
|
|
412
|
+
* ESM loader throws on a missing named export.
|
|
413
|
+
*/
|
|
414
|
+
export function studioMapsInstruction(options: { pin?: string } = {}): string {
|
|
415
|
+
if (!mapsExportsPublished(options.pin)) return "";
|
|
416
|
+
const names = STUDIO_SDK_CONTRACT.mapsExports.join(", ");
|
|
417
|
+
return `Maps on listing detail: from \`${STUDIO_SDK_PACKAGE}\` import ${names}. \`listing.location.coordinates\` is already masked by the site's privacy settings (≈100 m by default) — pass the listing object as-is; never un-mask, never re-geocode the street address to get a sharper point, never add decimals (\`maxDecimals\` can only coarsen). Always pass \`siteId\` (the resolved site id / publishable key) so maps.fndn.ai meters the site. Static map: \`const mapSrc = listingStaticMapUrl(listing, { width: 640, height: 320, zoom: 15, style: "roadmap", siteId })\` then \`{mapSrc ? <img src={mapSrc} alt={model.location.label} /> : null}\` — \`null\` means no coordinates, so omit the block (never a placeholder image). Zoom is capped by the coordinate precision (16 on the default mask); do not work around it. Street View: on the server page \`const sv = await listingStreetViewAvailable(listing, { siteId })\` (metadata is free), and only when \`sv.available\` render \`<img src={listingStreetViewUrl(listing, { width: 640, height: 400, siteId })} alt="Street View" />\` — the image is billed per load. Neighbourhood outline on an interactive map: load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` (never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`); in \`initMap\` do \`const outline = await neighborhoodBoundaryLayer(listing.location.city, listing.location.neighborhood, { siteId })\` and \`if (outline.feature) map.data.addGeoJson(outline.feature)\`; with MapLibre the vector source url is \`boundaryLayerUrl(listing.location.city)\`. Travel time (“quanto tempo até…”): \`const trip = await travelTimeFromListing(listing, destination, { mode: "driving", siteId })\` gives \`{ minutes, distanceKm }\` or \`null\` (hide the row). Every uncached call is a billed Google Directions request: call it on demand — a destination the visitor typed, or at most one fixed landmark per listing page — never per listing card, never inside a search loop, keep the SDK cache on (default 15 min LRU, \`cache: null\` only in tests), and do not re-run it on every render.`;
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
/**
|
|
421
|
+
* Search-page map mode. Empty below `mapsSince`. Studio injects this only
|
|
422
|
+
* when the site chose list and map. Listing-detail helpers stay out of it.
|
|
423
|
+
*/
|
|
424
|
+
export function studioMapSearchInstruction(
|
|
425
|
+
options: { pin?: string } = {}
|
|
426
|
+
): string {
|
|
427
|
+
if (!mapsExportsPublished(options.pin)) return "";
|
|
428
|
+
return `Map search on \`/imoveis\` (list and map of the same query). The list stays: keep \`usePublicSearch\` for the list, including its sort and pagination. The visitor switches on the same page. \`?modo=mapa\` is the map — read it on first paint. The list is the URL without \`modo\`; do not write \`modo=lista\` or \`modo=grade\`. Choosing the map sets \`modo=mapa\` and drops \`page\`. Choosing the list removes \`modo\`. On the map, hide sort and pagination. Do not add a map pager. The heading stays. Filters apply to both. Load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` — never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`, never \`maps.googleapis.com\`, never \`@vis.gl/react-google-maps\`. From \`${STUDIO_SDK_PACKAGE}/react\` import useMapSearch; it fetches, debounces, and clusters. \`const map = useMapSearch({ siteId, baseUrl: GARAGEM_API_BASE, bounds, zoom, q, sort, location, filters, publishableKey })\` with the same q, sort, location, filters, and publishableKey as the list. Pass the map's current zoom on every zoom change, including after a cluster click. Changing zoom recomputes \`map.clusters\` and does not refetch; a bounds change refetches. Do not send filter_by, vector_query, or nl_query from the browser. Request page 1 and pageSize at most 100. Do not walk totalPages. Pins are the masked coordinates the API returned — plot them as returned, never geocode the street. Render \`map.clusters\` with \`google.maps.Marker\` (no map id needed), in two styles that never look alike. A cluster (\`count > 1\`) is a filled circle in the brand color with a white border and the white count as its label. A listing (\`count === 1\` with \`cluster.pin\`) is a white rounded-rectangle chip with a brand-color border, labelled with the short price in the brand color ("R$ 850 mil", "R$ 1,2 mi"; "Consulte" when the price is null or 0): \`icon: { path: "M-34,-12 h68 a6,6 0 0 1 6,6 v12 a6,6 0 0 1 -6,6 h-68 a6,6 0 0 1 -6,-6 v-12 a6,6 0 0 1 6,-6 z", fillColor: "#ffffff", fillOpacity: 1, strokeColor: brand, strokeWeight: 1.5, scale: 1, labelOrigin: new google.maps.Point(0, 0) }\`. Never draw a listing as a dot or a circle, and never without its price. Clicking a listing selects it and shows its card. Clicking a cluster opens its members: \`const members = map.pins.filter((pin) => cluster.pinIds.includes(pin.id))\`, then \`fitBounds\` a LatLngBounds of their coordinates with about 64px padding, so the listings land inside the new view and split into chips. Do not step the zoom around \`cluster.lat\`/\`cluster.lng\`: that point is approximate and the area around it can come back empty. When every member has the same coordinates, or the map is already at zoom 18, do not zoom: open a small list of those listings, each with its price and a link. Layout, top to bottom: query, heading, toolbar, then the view. On desktop the toolbar is one row: featured filters on the left, and the list/map toggle immediately beside the sort select on the right. On a narrow screen the filters stay in one horizontal scroll that does not wrap, and the toggle plus the sort sit together on the row below that scroll. On the map the sort is hidden, so the toggle keeps that place beside where the sort was. In map mode the map fills the remaining viewport height, with a minimum of about 240px. Keep the hook's 400ms viewport debounce. A drawn polygon is not required. Do not add a separate /mapa route, a regions page, or a map on the listing page. Do not call Street View or travel time inside the map search.`;
|
|
429
|
+
}
|
|
430
|
+
|
|
374
431
|
/** True when the pinned tarball ships the market-data helpers. */
|
|
375
432
|
export function marketExportsAvailableAt(pin: string): boolean {
|
|
376
433
|
return compareSemver(pin, STUDIO_SDK_CONTRACT.marketExportsSince) >= 0;
|
|
@@ -449,6 +506,13 @@ export function studioCodegenContractViolations(text: string): string[] {
|
|
|
449
506
|
violations.push(name);
|
|
450
507
|
}
|
|
451
508
|
}
|
|
509
|
+
if (!mapsExportsPublished()) {
|
|
510
|
+
for (const name of STUDIO_SDK_CONTRACT.mapsExports) {
|
|
511
|
+
if (mentionsExportName(text, name) && !violations.includes(name)) {
|
|
512
|
+
violations.push(name);
|
|
513
|
+
}
|
|
514
|
+
}
|
|
515
|
+
}
|
|
452
516
|
for (const name of STUDIO_SDK_CONTRACT.unpublishedPhotoExports) {
|
|
453
517
|
if (mentionsExportName(text, name) && !violations.includes(name)) {
|
|
454
518
|
violations.push(name);
|
|
@@ -0,0 +1,275 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Types for the maps.fndn.ai helpers (`./maps`). Everything here works on
|
|
3
|
+
* the coordinates the public listings API already returns — those are
|
|
4
|
+
* masked per site (≈100 m by default) and the helpers never add precision.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import type { FetchLike } from "./fetchers";
|
|
8
|
+
|
|
9
|
+
/** `{ lat, lng }` pair as returned on `listing.location.coordinates`. */
|
|
10
|
+
export interface MapsCoordinates {
|
|
11
|
+
lat: number;
|
|
12
|
+
lng: number;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Anything carrying a public listing location: `Listing`, `ListingDetail`,
|
|
17
|
+
* a card model, or a bare `{ location: { coordinates } }`.
|
|
18
|
+
*/
|
|
19
|
+
export type ListingWithLocation =
|
|
20
|
+
| {
|
|
21
|
+
location?: { coordinates?: MapsCoordinates | null } | null;
|
|
22
|
+
}
|
|
23
|
+
| null
|
|
24
|
+
| undefined;
|
|
25
|
+
|
|
26
|
+
export interface MapsBaseOptions {
|
|
27
|
+
/** maps.fndn.ai origin. Defaults to `https://maps.fndn.ai`. */
|
|
28
|
+
mapsBaseUrl?: string;
|
|
29
|
+
/**
|
|
30
|
+
* Site id (or publishable key) used to meter this site's usage on
|
|
31
|
+
* maps.fndn.ai. Sent as the `site` query param on image URLs and as the
|
|
32
|
+
* `X-Garagem-Site` header on fetches. Optional today; it only labels
|
|
33
|
+
* metrics and the per-site rate limit, it is not authentication.
|
|
34
|
+
*/
|
|
35
|
+
siteId?: string;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export interface MapsFetchOptions extends MapsBaseOptions {
|
|
39
|
+
/** Override the fetch implementation (testing, edge runtimes, retries). */
|
|
40
|
+
fetch?: FetchLike;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Google Static Maps map type. `style` is the SDK-facing alias. */
|
|
44
|
+
export type StaticMapStyle = "roadmap" | "satellite" | "terrain" | "hybrid";
|
|
45
|
+
|
|
46
|
+
export interface StaticMapOptions extends MapsBaseOptions {
|
|
47
|
+
/** Pixels, 1–640 (Google Static Maps ceiling). Default 600. */
|
|
48
|
+
width?: number;
|
|
49
|
+
/** Pixels, 1–640. Default 300. */
|
|
50
|
+
height?: number;
|
|
51
|
+
/**
|
|
52
|
+
* 1–21. Default 15. Capped by the coordinate precision the API applied:
|
|
53
|
+
* a ≈100 m masked point is never rendered above zoom 16, so the pin does
|
|
54
|
+
* not pretend to know the exact building. See `maxZoomForCoordinates`.
|
|
55
|
+
*/
|
|
56
|
+
zoom?: number;
|
|
57
|
+
/** 1 or 2 (retina). Default 2. */
|
|
58
|
+
scale?: 1 | 2;
|
|
59
|
+
/** Map style. Default roadmap. */
|
|
60
|
+
style?: StaticMapStyle;
|
|
61
|
+
/** Marker color (Google color name or `0xRRGGBB`). Default red. */
|
|
62
|
+
markerColor?: string;
|
|
63
|
+
/** Hide points of interest. Default false. */
|
|
64
|
+
hidePoi?: boolean;
|
|
65
|
+
/**
|
|
66
|
+
* Max decimal places to send. Only ever *reduces* precision (e.g. send
|
|
67
|
+
* 2 decimals ≈ 1 km for a neighbourhood teaser); it cannot recover
|
|
68
|
+
* precision the API removed.
|
|
69
|
+
*/
|
|
70
|
+
maxDecimals?: number;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export interface StreetViewOptions extends MapsBaseOptions {
|
|
74
|
+
/** Pixels, 1–640. Default 640. */
|
|
75
|
+
width?: number;
|
|
76
|
+
/** Pixels, 1–640. Default 640. */
|
|
77
|
+
height?: number;
|
|
78
|
+
/** Field of view in degrees, 10–120. Default 90. */
|
|
79
|
+
fov?: number;
|
|
80
|
+
/** Compass heading 0–360. Default 0. */
|
|
81
|
+
heading?: number;
|
|
82
|
+
/** Camera pitch -90–90. Default 10. */
|
|
83
|
+
pitch?: number;
|
|
84
|
+
/** See `StaticMapOptions.maxDecimals`. */
|
|
85
|
+
maxDecimals?: number;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export interface StreetViewAvailabilityOptions extends MapsFetchOptions {
|
|
89
|
+
/** See `StaticMapOptions.maxDecimals`. */
|
|
90
|
+
maxDecimals?: number;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
export interface StreetViewAvailability {
|
|
94
|
+
/** `true` when Google has a panorama near the (masked) coordinates. */
|
|
95
|
+
available: boolean;
|
|
96
|
+
/** Google metadata status: `OK`, `ZERO_RESULTS`, `ERROR`, … */
|
|
97
|
+
status: string;
|
|
98
|
+
/** Panorama id when available. */
|
|
99
|
+
panoId?: string;
|
|
100
|
+
/** Capture date (`YYYY-MM`) when available. */
|
|
101
|
+
date?: string;
|
|
102
|
+
/** maps.fndn.ai metadata URL that was queried. */
|
|
103
|
+
url: string;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** Cities with boundary layers on maps.fndn.ai. Other slugs pass through. */
|
|
107
|
+
export type BoundaryCity = "sao_paulo" | "rio_de_janeiro" | (string & {});
|
|
108
|
+
|
|
109
|
+
export type BoundaryLayerUrlKind =
|
|
110
|
+
/** `GET /v1/layers/:id` — layer descriptor JSON. */
|
|
111
|
+
| "layer"
|
|
112
|
+
/** TileJSON for MapLibre `addSource({ type: "vector", url })`. */
|
|
113
|
+
| "tilejson"
|
|
114
|
+
/** `{z}/{x}/{y}` vector tile template. */
|
|
115
|
+
| "tiles"
|
|
116
|
+
/** Whole-city GeoJSON FeatureCollection. */
|
|
117
|
+
| "geojson";
|
|
118
|
+
|
|
119
|
+
export interface BoundaryLayerOptions extends MapsBaseOptions {
|
|
120
|
+
kind?: BoundaryLayerUrlKind;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
export interface BoundarySourceLayer {
|
|
124
|
+
id: string;
|
|
125
|
+
label: string;
|
|
126
|
+
minzoom?: number;
|
|
127
|
+
maxzoom?: number;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** Subset of the maps.fndn.ai `/v1/layers/:id` descriptor the SDK exposes. */
|
|
131
|
+
export interface BoundaryLayer {
|
|
132
|
+
id: string;
|
|
133
|
+
name: string;
|
|
134
|
+
description: string;
|
|
135
|
+
city?: string;
|
|
136
|
+
/** `{z}/{x}/{y}` template. */
|
|
137
|
+
tiles: string;
|
|
138
|
+
tilejson: string;
|
|
139
|
+
/** Whole-city GeoJSON, when published. */
|
|
140
|
+
geojson?: string;
|
|
141
|
+
sourceLayers: BoundarySourceLayer[];
|
|
142
|
+
minzoom: number;
|
|
143
|
+
maxzoom: number;
|
|
144
|
+
attribution?: string;
|
|
145
|
+
available: boolean;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** Minimal GeoJSON shapes so the SDK does not depend on `@types/geojson`. */
|
|
149
|
+
export interface BoundaryGeometry {
|
|
150
|
+
type: string;
|
|
151
|
+
coordinates: unknown;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
export interface BoundaryFeature {
|
|
155
|
+
type: "Feature";
|
|
156
|
+
properties: Record<string, unknown> & { name?: string; level?: string };
|
|
157
|
+
geometry: BoundaryGeometry | null;
|
|
158
|
+
[key: string]: unknown;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
export interface BoundaryFeatureCollection {
|
|
162
|
+
type: "FeatureCollection";
|
|
163
|
+
features: BoundaryFeature[];
|
|
164
|
+
count?: number;
|
|
165
|
+
source?: string;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
export interface NeighborhoodBoundaryOptions extends MapsFetchOptions {
|
|
169
|
+
/**
|
|
170
|
+
* Boundary dataset. Default `listaaberta` (SP districts / RJ
|
|
171
|
+
* neighbourhoods with IPTU stats); `osm` covers more cities.
|
|
172
|
+
*/
|
|
173
|
+
source?: "listaaberta" | "osm" | "all";
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
export interface NeighborhoodBoundary {
|
|
177
|
+
city: string;
|
|
178
|
+
neighborhood: string;
|
|
179
|
+
/** The matched outline, or `null` when nothing matched. */
|
|
180
|
+
feature: BoundaryFeature | null;
|
|
181
|
+
/** Every candidate when the name matched more than one feature. */
|
|
182
|
+
candidates: BoundaryFeature[];
|
|
183
|
+
/** GeoJSON URL that was queried (safe to pass to MapLibre `data`). */
|
|
184
|
+
url: string;
|
|
185
|
+
/** Vector tile template for the city's boundary layer. */
|
|
186
|
+
tiles: string;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
export type TravelMode = "driving" | "walking" | "bicycling" | "transit";
|
|
190
|
+
|
|
191
|
+
/** Coordinates, or a free-text address geocoded on maps.fndn.ai first. */
|
|
192
|
+
export type TravelDestination = MapsCoordinates | string;
|
|
193
|
+
|
|
194
|
+
export interface TravelTimeOptions extends MapsFetchOptions {
|
|
195
|
+
/** Default `driving`. */
|
|
196
|
+
mode?: TravelMode;
|
|
197
|
+
/** Client-side cache. Defaults to a module-level LRU; pass `null` to skip. */
|
|
198
|
+
cache?: TravelTimeCache | null;
|
|
199
|
+
/** See `StaticMapOptions.maxDecimals`. */
|
|
200
|
+
maxDecimals?: number;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
export interface TravelTime {
|
|
204
|
+
/** Rounded travel time in minutes (minimum 1 when a route exists). */
|
|
205
|
+
minutes: number;
|
|
206
|
+
seconds: number;
|
|
207
|
+
distanceMeters: number;
|
|
208
|
+
/** Distance rounded to one decimal. */
|
|
209
|
+
distanceKm: number;
|
|
210
|
+
mode: TravelMode;
|
|
211
|
+
origin: MapsCoordinates;
|
|
212
|
+
destination: MapsCoordinates;
|
|
213
|
+
/** `true` when served from the client-side cache. */
|
|
214
|
+
cached: boolean;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
export interface TravelTimesOptions extends MapsFetchOptions {
|
|
218
|
+
/** See `StaticMapOptions.maxDecimals`. */
|
|
219
|
+
maxDecimals?: number;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/** One route-matrix element; `null` when Google found no route. */
|
|
223
|
+
export interface TravelTimeElement {
|
|
224
|
+
minutes: number;
|
|
225
|
+
seconds: number;
|
|
226
|
+
destination: MapsCoordinates;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
export interface TravelTimeCacheOptions {
|
|
230
|
+
/** Default 200 entries. */
|
|
231
|
+
maxEntries?: number;
|
|
232
|
+
/** Default 15 minutes. */
|
|
233
|
+
ttlMs?: number;
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
export interface TravelTimeCache {
|
|
237
|
+
get(key: string): TravelTime | undefined;
|
|
238
|
+
set(key: string, value: TravelTime): void;
|
|
239
|
+
clear(): void;
|
|
240
|
+
readonly size: number;
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
// ---------------------------------------------------------------------------
|
|
244
|
+
// Map search (friendly public listings route, not raw Typesense)
|
|
245
|
+
// ---------------------------------------------------------------------------
|
|
246
|
+
|
|
247
|
+
/** Viewport rectangle in degrees. `east` must be greater than `west`. */
|
|
248
|
+
export interface MapBounds {
|
|
249
|
+
north: number;
|
|
250
|
+
south: number;
|
|
251
|
+
east: number;
|
|
252
|
+
west: number;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/** `[lat, lng]` vertices. Not GeoJSON `[lng, lat]`. */
|
|
256
|
+
export type MapPolygon = Array<[number, number]>;
|
|
257
|
+
|
|
258
|
+
/** Pin plotted from a public listing. Coordinates are already masked. */
|
|
259
|
+
export interface MapPin {
|
|
260
|
+
id: string;
|
|
261
|
+
lat: number;
|
|
262
|
+
lng: number;
|
|
263
|
+
price: number | null;
|
|
264
|
+
coverImage: string | null;
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/** One grid cell. `count === 1` keeps the pin's own coordinates. */
|
|
268
|
+
export interface MapPinCluster {
|
|
269
|
+
id: string;
|
|
270
|
+
lat: number;
|
|
271
|
+
lng: number;
|
|
272
|
+
count: number;
|
|
273
|
+
pinIds: string[];
|
|
274
|
+
pin: MapPin | null;
|
|
275
|
+
}
|
package/src/types.ts
CHANGED
|
@@ -275,6 +275,18 @@ export interface QueryListingsParams {
|
|
|
275
275
|
q?: string;
|
|
276
276
|
filters?: QueryListingsFilters;
|
|
277
277
|
location?: QueryListingsLocation | QueryListingsLocation[];
|
|
278
|
+
/**
|
|
279
|
+
* Map viewport. The server builds a `coordinates:(…)` polygon from these
|
|
280
|
+
* numbers. Ignored when `polygon` is also set.
|
|
281
|
+
*/
|
|
282
|
+
bounds?: {
|
|
283
|
+
north: number;
|
|
284
|
+
south: number;
|
|
285
|
+
east: number;
|
|
286
|
+
west: number;
|
|
287
|
+
};
|
|
288
|
+
/** Drawn area as `[lat, lng]` pairs, not GeoJSON `[lng, lat]`. */
|
|
289
|
+
polygon?: Array<[number, number]>;
|
|
278
290
|
}
|
|
279
291
|
|
|
280
292
|
export interface QueryListingsResult {
|