@garagem-ai/site-sdk 0.10.1 → 0.11.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.
@@ -1,3 +1,422 @@
1
+ /** Custom fetch implementation. Defaults to the global `fetch`. */
2
+ type FetchLike = typeof fetch;
3
+ interface BaseOptions {
4
+ /** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
5
+ baseUrl?: string;
6
+ /** Override the fetch implementation (testing, edge runtimes, retries). */
7
+ fetch?: FetchLike;
8
+ /**
9
+ * Next.js App Router caching hints. Ignored on runtimes that don't
10
+ * understand them.
11
+ */
12
+ next?: RequestNextOptions;
13
+ /**
14
+ * Site publishable key (`pk_live_…`) from Configurações → Sites → API
15
+ * pública. Not a secret. Omit it and the request stays anonymous.
16
+ */
17
+ publishableKey?: string;
18
+ }
19
+ interface GetListingsOptions extends BaseOptions {
20
+ siteId: string;
21
+ filters?: ListingFilters;
22
+ }
23
+ interface GetListingOptions extends BaseOptions {
24
+ siteId: string;
25
+ listingId: string;
26
+ }
27
+ interface GetSiteOptions extends BaseOptions {
28
+ /** Look up by site ID, or… */
29
+ siteId?: string;
30
+ /** …by domain. Exactly one of `siteId` / `domain` must be provided. */
31
+ domain?: string;
32
+ }
33
+ interface SearchListingsOptions extends BaseOptions {
34
+ siteId: string;
35
+ params: SearchListingsParams;
36
+ }
37
+ interface GetSearchUiOptions extends BaseOptions {
38
+ siteId: string;
39
+ }
40
+ interface QueryListingsOptions extends BaseOptions {
41
+ siteId: string;
42
+ params?: QueryListingsParams;
43
+ /** Aborts the listings request. Stale map pans use this. */
44
+ signal?: AbortSignal;
45
+ }
46
+ interface GetSimilarListingsOptions extends BaseOptions {
47
+ siteId: string;
48
+ listingId: string;
49
+ /** Max similar cards to return (API default 6, cap 12). */
50
+ limit?: number;
51
+ }
52
+ interface GetCmsCollectionsOptions extends BaseOptions {
53
+ siteId: string;
54
+ }
55
+ interface GetCmsCollectionOptions extends BaseOptions {
56
+ siteId: string;
57
+ slug: string;
58
+ }
59
+ interface GetCmsEntriesOptions extends BaseOptions {
60
+ siteId: string;
61
+ collection: string;
62
+ limit?: number;
63
+ offset?: number;
64
+ }
65
+ interface GetCmsEntryOptions extends BaseOptions {
66
+ siteId: string;
67
+ collection: string;
68
+ slug: string;
69
+ }
70
+ /** Error thrown when a fetcher hits a non-2xx response. */
71
+ declare class GaragemSdkError extends Error {
72
+ readonly status: number;
73
+ readonly url: string;
74
+ /** Machine reason from the JSON body (`invalid_publishable_key`, `rate_limited`, …). */
75
+ readonly reason: string | null;
76
+ /**
77
+ * Seconds to wait before retrying. Set on HTTP 429 from `Retry-After`
78
+ * or the body's `retryAfterSeconds`. `null` when the response has neither.
79
+ */
80
+ readonly retryAfter: number | null;
81
+ constructor(message: string, info: {
82
+ status: number;
83
+ url: string;
84
+ reason?: string | null;
85
+ retryAfter?: number | null;
86
+ });
87
+ }
88
+ /**
89
+ * Fetch a paginated list of listings for a given site.
90
+ *
91
+ * @example
92
+ * const { listings } = await getListings({
93
+ * siteId: "abc",
94
+ * filters: { city: "São Paulo", limit: 24 },
95
+ * next: { revalidate: 300, tags: [`site:abc:listings`] },
96
+ * });
97
+ */
98
+ declare function getListings(options: GetListingsOptions): Promise<ListingsResult>;
99
+ /**
100
+ * Fetch a single listing's full detail (amenities, gallery, building).
101
+ * `listingId` accepts a code, UUID, or `id-{code}` URL segment.
102
+ */
103
+ declare function getListing(options: GetListingOptions): Promise<ListingDetail>;
104
+ /**
105
+ * Resolve a site's public profile by ID or by domain. Returns `null`
106
+ * when the site does not exist or the host is unrecognized.
107
+ *
108
+ * @example
109
+ * const site = await getSite({ domain: "imobiliariax.com.br" });
110
+ * if (!site) return notFound();
111
+ */
112
+ declare function getSite(options: GetSiteOptions): Promise<Site | null>;
113
+ /**
114
+ * Advanced search escape hatch.
115
+ *
116
+ * Calls `POST /api/sites/{siteId}/search` directly and returns the raw
117
+ * Typesense response (`{ found, page, hits: [{ document, ... }], ... }`).
118
+ * Use when `queryListings` isn't expressive enough — faceted search,
119
+ * multi-field sort, custom grouping, etc.
120
+ *
121
+ * @example
122
+ * const result = await searchListings({
123
+ * siteId: "abc",
124
+ * params: {
125
+ * q: "frente mar",
126
+ * query_by: "title,description,neighborhood",
127
+ * filter_by: "businessType:=sale && bedrooms:>=3",
128
+ * sort_by: "price:asc",
129
+ * per_page: 24,
130
+ * page: 1,
131
+ * facet_by: "neighborhood,propertyType",
132
+ * },
133
+ * });
134
+ * for (const hit of result.hits) {
135
+ * console.log(hit.document, hit.highlight);
136
+ * }
137
+ */
138
+ declare function searchListings<TDocument = Record<string, unknown>>(options: SearchListingsOptions): Promise<SearchListingsResult<TDocument>>;
139
+ /**
140
+ * Tenant search schema: filters, slugs, sort tokens, defaultLimit 12.
141
+ * Use this to render the search UI — do not hardcode property types.
142
+ */
143
+ declare function getSearchUi(options: GetSearchUiOptions): Promise<SearchUi>;
144
+ /**
145
+ * Friendly catalog search (editor combinators). Prefer this over
146
+ * `searchListings` — that helper is a raw Typesense escape hatch.
147
+ */
148
+ declare function queryListings(options: QueryListingsOptions): Promise<QueryListingsResult>;
149
+ /**
150
+ * Fetch similar listings for a detail page carousel.
151
+ * Returns an empty list when the reference listing is missing.
152
+ */
153
+ declare function getSimilarListings(options: GetSimilarListingsOptions): Promise<SimilarListingsResult>;
154
+ /** List CMS collections for a site. */
155
+ declare function getCmsCollections(options: GetCmsCollectionsOptions): Promise<CmsCollection[]>;
156
+ /** Fetch one CMS collection schema by slug. */
157
+ declare function getCmsCollection(options: GetCmsCollectionOptions): Promise<CmsCollection>;
158
+ /** List published CMS entries for a collection. */
159
+ declare function getCmsEntries(options: GetCmsEntriesOptions): Promise<CmsEntriesResult>;
160
+ /** Fetch one published CMS entry by slug. */
161
+ declare function getCmsEntry(options: GetCmsEntryOptions): Promise<CmsEntry>;
162
+
163
+ /**
164
+ * Types for the maps.fndn.ai helpers (`./maps`). Everything here works on
165
+ * the coordinates the public listings API already returns — those are
166
+ * masked per site (≈100 m by default) and the helpers never add precision.
167
+ */
168
+
169
+ /** `{ lat, lng }` pair as returned on `listing.location.coordinates`. */
170
+ interface MapsCoordinates {
171
+ lat: number;
172
+ lng: number;
173
+ }
174
+ /**
175
+ * Anything carrying a public listing location: `Listing`, `ListingDetail`,
176
+ * a card model, or a bare `{ location: { coordinates } }`.
177
+ */
178
+ type ListingWithLocation = {
179
+ location?: {
180
+ coordinates?: MapsCoordinates | null;
181
+ } | null;
182
+ } | null | undefined;
183
+ interface MapsBaseOptions {
184
+ /** maps.fndn.ai origin. Defaults to `https://maps.fndn.ai`. */
185
+ mapsBaseUrl?: string;
186
+ /**
187
+ * Site id (or publishable key) used to meter this site's usage on
188
+ * maps.fndn.ai. Sent as the `site` query param on image URLs and as the
189
+ * `X-Garagem-Site` header on fetches. Optional today; it only labels
190
+ * metrics and the per-site rate limit, it is not authentication.
191
+ */
192
+ siteId?: string;
193
+ }
194
+ interface MapsFetchOptions extends MapsBaseOptions {
195
+ /** Override the fetch implementation (testing, edge runtimes, retries). */
196
+ fetch?: FetchLike;
197
+ }
198
+ /** Google Static Maps map type. `style` is the SDK-facing alias. */
199
+ type StaticMapStyle = "roadmap" | "satellite" | "terrain" | "hybrid";
200
+ interface StaticMapOptions extends MapsBaseOptions {
201
+ /** Pixels, 1–640 (Google Static Maps ceiling). Default 600. */
202
+ width?: number;
203
+ /** Pixels, 1–640. Default 300. */
204
+ height?: number;
205
+ /**
206
+ * 1–21. Default 15. Capped by the coordinate precision the API applied:
207
+ * a ≈100 m masked point is never rendered above zoom 16, so the pin does
208
+ * not pretend to know the exact building. See `maxZoomForCoordinates`.
209
+ */
210
+ zoom?: number;
211
+ /** 1 or 2 (retina). Default 2. */
212
+ scale?: 1 | 2;
213
+ /** Map style. Default roadmap. */
214
+ style?: StaticMapStyle;
215
+ /** Marker color (Google color name or `0xRRGGBB`). Default red. */
216
+ markerColor?: string;
217
+ /** Hide points of interest. Default false. */
218
+ hidePoi?: boolean;
219
+ /**
220
+ * Max decimal places to send. Only ever *reduces* precision (e.g. send
221
+ * 2 decimals ≈ 1 km for a neighbourhood teaser); it cannot recover
222
+ * precision the API removed.
223
+ */
224
+ maxDecimals?: number;
225
+ }
226
+ interface StreetViewOptions extends MapsBaseOptions {
227
+ /** Pixels, 1–640. Default 640. */
228
+ width?: number;
229
+ /** Pixels, 1–640. Default 640. */
230
+ height?: number;
231
+ /** Field of view in degrees, 10–120. Default 90. */
232
+ fov?: number;
233
+ /** Compass heading 0–360. Default 0. */
234
+ heading?: number;
235
+ /** Camera pitch -90–90. Default 10. */
236
+ pitch?: number;
237
+ /** See `StaticMapOptions.maxDecimals`. */
238
+ maxDecimals?: number;
239
+ }
240
+ interface StreetViewAvailabilityOptions extends MapsFetchOptions {
241
+ /** See `StaticMapOptions.maxDecimals`. */
242
+ maxDecimals?: number;
243
+ }
244
+ interface StreetViewAvailability {
245
+ /** `true` when Google has a panorama near the (masked) coordinates. */
246
+ available: boolean;
247
+ /** Google metadata status: `OK`, `ZERO_RESULTS`, `ERROR`, … */
248
+ status: string;
249
+ /** Panorama id when available. */
250
+ panoId?: string;
251
+ /** Capture date (`YYYY-MM`) when available. */
252
+ date?: string;
253
+ /** maps.fndn.ai metadata URL that was queried. */
254
+ url: string;
255
+ }
256
+ /** Cities with boundary layers on maps.fndn.ai. Other slugs pass through. */
257
+ type BoundaryCity = "sao_paulo" | "rio_de_janeiro" | (string & {});
258
+ type BoundaryLayerUrlKind =
259
+ /** `GET /v1/layers/:id` — layer descriptor JSON. */
260
+ "layer"
261
+ /** TileJSON for MapLibre `addSource({ type: "vector", url })`. */
262
+ | "tilejson"
263
+ /** `{z}/{x}/{y}` vector tile template. */
264
+ | "tiles"
265
+ /** Whole-city GeoJSON FeatureCollection. */
266
+ | "geojson";
267
+ interface BoundaryLayerOptions extends MapsBaseOptions {
268
+ kind?: BoundaryLayerUrlKind;
269
+ }
270
+ interface BoundarySourceLayer {
271
+ id: string;
272
+ label: string;
273
+ minzoom?: number;
274
+ maxzoom?: number;
275
+ }
276
+ /** Subset of the maps.fndn.ai `/v1/layers/:id` descriptor the SDK exposes. */
277
+ interface BoundaryLayer {
278
+ id: string;
279
+ name: string;
280
+ description: string;
281
+ city?: string;
282
+ /** `{z}/{x}/{y}` template. */
283
+ tiles: string;
284
+ tilejson: string;
285
+ /** Whole-city GeoJSON, when published. */
286
+ geojson?: string;
287
+ sourceLayers: BoundarySourceLayer[];
288
+ minzoom: number;
289
+ maxzoom: number;
290
+ attribution?: string;
291
+ available: boolean;
292
+ }
293
+ /** Minimal GeoJSON shapes so the SDK does not depend on `@types/geojson`. */
294
+ interface BoundaryGeometry {
295
+ type: string;
296
+ coordinates: unknown;
297
+ }
298
+ interface BoundaryFeature {
299
+ type: "Feature";
300
+ properties: Record<string, unknown> & {
301
+ name?: string;
302
+ level?: string;
303
+ };
304
+ geometry: BoundaryGeometry | null;
305
+ [key: string]: unknown;
306
+ }
307
+ interface BoundaryFeatureCollection {
308
+ type: "FeatureCollection";
309
+ features: BoundaryFeature[];
310
+ count?: number;
311
+ source?: string;
312
+ }
313
+ interface NeighborhoodBoundaryOptions extends MapsFetchOptions {
314
+ /**
315
+ * Boundary dataset. Default `listaaberta` (SP districts / RJ
316
+ * neighbourhoods with IPTU stats); `osm` covers more cities.
317
+ */
318
+ source?: "listaaberta" | "osm" | "all";
319
+ }
320
+ interface NeighborhoodBoundary {
321
+ city: string;
322
+ neighborhood: string;
323
+ /** The matched outline, or `null` when nothing matched. */
324
+ feature: BoundaryFeature | null;
325
+ /** Every candidate when the name matched more than one feature. */
326
+ candidates: BoundaryFeature[];
327
+ /** GeoJSON URL that was queried (safe to pass to MapLibre `data`). */
328
+ url: string;
329
+ /** Vector tile template for the city's boundary layer. */
330
+ tiles: string;
331
+ }
332
+ type TravelMode = "driving" | "walking" | "bicycling" | "transit";
333
+ /** Coordinates, or a free-text address geocoded on maps.fndn.ai first. */
334
+ type TravelDestination = MapsCoordinates | string;
335
+ interface TravelTimeOptions extends MapsFetchOptions {
336
+ /** Default `driving`. */
337
+ mode?: TravelMode;
338
+ /** Client-side cache. Defaults to a module-level LRU; pass `null` to skip. */
339
+ cache?: TravelTimeCache | null;
340
+ /** See `StaticMapOptions.maxDecimals`. */
341
+ maxDecimals?: number;
342
+ }
343
+ interface TravelTime {
344
+ /** Rounded travel time in minutes (minimum 1 when a route exists). */
345
+ minutes: number;
346
+ seconds: number;
347
+ distanceMeters: number;
348
+ /** Distance rounded to one decimal. */
349
+ distanceKm: number;
350
+ mode: TravelMode;
351
+ origin: MapsCoordinates;
352
+ destination: MapsCoordinates;
353
+ /** `true` when served from the client-side cache. */
354
+ cached: boolean;
355
+ }
356
+ interface TravelTimesOptions extends MapsFetchOptions {
357
+ /** See `StaticMapOptions.maxDecimals`. */
358
+ maxDecimals?: number;
359
+ }
360
+ /** One route-matrix element; `null` when Google found no route. */
361
+ interface TravelTimeElement {
362
+ minutes: number;
363
+ seconds: number;
364
+ destination: MapsCoordinates;
365
+ }
366
+ interface TravelTimeCacheOptions {
367
+ /** Default 200 entries. */
368
+ maxEntries?: number;
369
+ /** Default 15 minutes. */
370
+ ttlMs?: number;
371
+ }
372
+ interface TravelTimeCache {
373
+ get(key: string): TravelTime | undefined;
374
+ set(key: string, value: TravelTime): void;
375
+ clear(): void;
376
+ readonly size: number;
377
+ }
378
+ /** Viewport rectangle in degrees. `east` must be greater than `west`. */
379
+ interface MapBounds {
380
+ north: number;
381
+ south: number;
382
+ east: number;
383
+ west: number;
384
+ }
385
+ /** `[lat, lng]` vertices. Not GeoJSON `[lng, lat]`. */
386
+ type MapPolygon = Array<[number, number]>;
387
+ /** Pin plotted from a public listing. Coordinates are already masked. */
388
+ interface MapPin {
389
+ id: string;
390
+ lat: number;
391
+ lng: number;
392
+ price: number | null;
393
+ coverImage: string | null;
394
+ }
395
+ /**
396
+ * Location group returned when the matches do not fit on one page. It sits
397
+ * on one of its own listings (masked like a pin) and `count` is the group's
398
+ * real total, so bucket counts add up to the search total.
399
+ */
400
+ interface MapBucket {
401
+ /** Location path, e.g. `SP · São Paulo · Pinheiros`. */
402
+ id: string;
403
+ lat: number;
404
+ lng: number;
405
+ count: number;
406
+ }
407
+ /**
408
+ * One grid cell. `count === 1` keeps the pin's own coordinates. A cell of
409
+ * buckets has empty `pinIds` and a null `pin`.
410
+ */
411
+ interface MapPinCluster {
412
+ id: string;
413
+ lat: number;
414
+ lng: number;
415
+ count: number;
416
+ pinIds: string[];
417
+ pin: MapPin | null;
418
+ }
419
+
1
420
  /**
2
421
  * Public types for the Garagem Sites SDK.
3
422
  *
@@ -5,6 +424,7 @@
5
424
  * Sites API (`/api/sites/...`). Treat them as the public contract —
6
425
  * additive changes only, never breaking.
7
426
  */
427
+
8
428
  /** Sale/rental indicator. The API may return additional string values; consumers should branch defensively. */
9
429
  type ListingBusinessType = "sale" | "rental" | (string & {});
10
430
  /** Whether the price is shown publicly or kept on request. */
@@ -291,6 +711,8 @@ interface QueryListingsParams {
291
711
  };
292
712
  /** Drawn area as `[lat, lng]` pairs, not GeoJSON `[lng, lat]`. */
293
713
  polygon?: Array<[number, number]>;
714
+ /** Map search: return `buckets` when the matches do not fit on page 1. */
715
+ buckets?: boolean;
294
716
  }
295
717
  interface QueryListingsResult {
296
718
  listings: Listing[];
@@ -298,6 +720,12 @@ interface QueryListingsResult {
298
720
  limit: number;
299
721
  total: number;
300
722
  totalPages: number;
723
+ /**
724
+ * Present only when `buckets` was requested, the matches overflow, and
725
+ * `total` counts one listing per match (no property collapse or partner
726
+ * listings). Otherwise map the page's pins.
727
+ */
728
+ buckets?: MapBucket[];
301
729
  }
302
730
  /**
303
731
  * Raw Typesense search parameters accepted by `searchListings`. Mirrors
@@ -409,178 +837,16 @@ interface CmsEntriesResult {
409
837
  offset: number;
410
838
  }
411
839
  /**
412
- * App Router caching hints passed straight through to the underlying
413
- * `fetch` call. See https://nextjs.org/docs/app/api-reference/functions/fetch.
414
- *
415
- * Typed loosely so this works in plain Node, Edge, Cloudflare Workers
416
- * and Bun runtimes without Next-specific types being mandatory.
417
- */
418
- interface RequestNextOptions {
419
- revalidate?: number | false;
420
- tags?: string[];
421
- }
422
-
423
- /** Custom fetch implementation. Defaults to the global `fetch`. */
424
- type FetchLike = typeof fetch;
425
- interface BaseOptions {
426
- /** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
427
- baseUrl?: string;
428
- /** Override the fetch implementation (testing, edge runtimes, retries). */
429
- fetch?: FetchLike;
430
- /**
431
- * Next.js App Router caching hints. Ignored on runtimes that don't
432
- * understand them.
433
- */
434
- next?: RequestNextOptions;
435
- /**
436
- * Site publishable key (`pk_live_…`) from Configurações → Sites → API
437
- * pública. Not a secret. Omit it and the request stays anonymous.
438
- */
439
- publishableKey?: string;
440
- }
441
- interface GetListingsOptions extends BaseOptions {
442
- siteId: string;
443
- filters?: ListingFilters;
444
- }
445
- interface GetListingOptions extends BaseOptions {
446
- siteId: string;
447
- listingId: string;
448
- }
449
- interface GetSiteOptions extends BaseOptions {
450
- /** Look up by site ID, or… */
451
- siteId?: string;
452
- /** …by domain. Exactly one of `siteId` / `domain` must be provided. */
453
- domain?: string;
454
- }
455
- interface SearchListingsOptions extends BaseOptions {
456
- siteId: string;
457
- params: SearchListingsParams;
458
- }
459
- interface GetSearchUiOptions extends BaseOptions {
460
- siteId: string;
461
- }
462
- interface QueryListingsOptions extends BaseOptions {
463
- siteId: string;
464
- params?: QueryListingsParams;
465
- /** Aborts the listings request. Stale map pans use this. */
466
- signal?: AbortSignal;
467
- }
468
- interface GetSimilarListingsOptions extends BaseOptions {
469
- siteId: string;
470
- listingId: string;
471
- /** Max similar cards to return (API default 6, cap 12). */
472
- limit?: number;
473
- }
474
- interface GetCmsCollectionsOptions extends BaseOptions {
475
- siteId: string;
476
- }
477
- interface GetCmsCollectionOptions extends BaseOptions {
478
- siteId: string;
479
- slug: string;
480
- }
481
- interface GetCmsEntriesOptions extends BaseOptions {
482
- siteId: string;
483
- collection: string;
484
- limit?: number;
485
- offset?: number;
486
- }
487
- interface GetCmsEntryOptions extends BaseOptions {
488
- siteId: string;
489
- collection: string;
490
- slug: string;
491
- }
492
- /** Error thrown when a fetcher hits a non-2xx response. */
493
- declare class GaragemSdkError extends Error {
494
- readonly status: number;
495
- readonly url: string;
496
- /** Machine reason from the JSON body (`invalid_publishable_key`, `rate_limited`, …). */
497
- readonly reason: string | null;
498
- /**
499
- * Seconds to wait before retrying. Set on HTTP 429 from `Retry-After`
500
- * or the body's `retryAfterSeconds`. `null` when the response has neither.
501
- */
502
- readonly retryAfter: number | null;
503
- constructor(message: string, info: {
504
- status: number;
505
- url: string;
506
- reason?: string | null;
507
- retryAfter?: number | null;
508
- });
509
- }
510
- /**
511
- * Fetch a paginated list of listings for a given site.
512
- *
513
- * @example
514
- * const { listings } = await getListings({
515
- * siteId: "abc",
516
- * filters: { city: "São Paulo", limit: 24 },
517
- * next: { revalidate: 300, tags: [`site:abc:listings`] },
518
- * });
519
- */
520
- declare function getListings(options: GetListingsOptions): Promise<ListingsResult>;
521
- /**
522
- * Fetch a single listing's full detail (amenities, gallery, building).
523
- * `listingId` accepts a code, UUID, or `id-{code}` URL segment.
524
- */
525
- declare function getListing(options: GetListingOptions): Promise<ListingDetail>;
526
- /**
527
- * Resolve a site's public profile by ID or by domain. Returns `null`
528
- * when the site does not exist or the host is unrecognized.
529
- *
530
- * @example
531
- * const site = await getSite({ domain: "imobiliariax.com.br" });
532
- * if (!site) return notFound();
533
- */
534
- declare function getSite(options: GetSiteOptions): Promise<Site | null>;
535
- /**
536
- * Advanced search escape hatch.
537
- *
538
- * Calls `POST /api/sites/{siteId}/search` directly and returns the raw
539
- * Typesense response (`{ found, page, hits: [{ document, ... }], ... }`).
540
- * Use when `queryListings` isn't expressive enough — faceted search,
541
- * multi-field sort, custom grouping, etc.
542
- *
543
- * @example
544
- * const result = await searchListings({
545
- * siteId: "abc",
546
- * params: {
547
- * q: "frente mar",
548
- * query_by: "title,description,neighborhood",
549
- * filter_by: "businessType:=sale && bedrooms:>=3",
550
- * sort_by: "price:asc",
551
- * per_page: 24,
552
- * page: 1,
553
- * facet_by: "neighborhood,propertyType",
554
- * },
555
- * });
556
- * for (const hit of result.hits) {
557
- * console.log(hit.document, hit.highlight);
558
- * }
559
- */
560
- declare function searchListings<TDocument = Record<string, unknown>>(options: SearchListingsOptions): Promise<SearchListingsResult<TDocument>>;
561
- /**
562
- * Tenant search schema: filters, slugs, sort tokens, defaultLimit 12.
563
- * Use this to render the search UI — do not hardcode property types.
564
- */
565
- declare function getSearchUi(options: GetSearchUiOptions): Promise<SearchUi>;
566
- /**
567
- * Friendly catalog search (editor combinators). Prefer this over
568
- * `searchListings` — that helper is a raw Typesense escape hatch.
569
- */
570
- declare function queryListings(options: QueryListingsOptions): Promise<QueryListingsResult>;
571
- /**
572
- * Fetch similar listings for a detail page carousel.
573
- * Returns an empty list when the reference listing is missing.
574
- */
575
- declare function getSimilarListings(options: GetSimilarListingsOptions): Promise<SimilarListingsResult>;
576
- /** List CMS collections for a site. */
577
- declare function getCmsCollections(options: GetCmsCollectionsOptions): Promise<CmsCollection[]>;
578
- /** Fetch one CMS collection schema by slug. */
579
- declare function getCmsCollection(options: GetCmsCollectionOptions): Promise<CmsCollection>;
580
- /** List published CMS entries for a collection. */
581
- declare function getCmsEntries(options: GetCmsEntriesOptions): Promise<CmsEntriesResult>;
582
- /** Fetch one published CMS entry by slug. */
583
- declare function getCmsEntry(options: GetCmsEntryOptions): Promise<CmsEntry>;
840
+ * App Router caching hints passed straight through to the underlying
841
+ * `fetch` call. See https://nextjs.org/docs/app/api-reference/functions/fetch.
842
+ *
843
+ * Typed loosely so this works in plain Node, Edge, Cloudflare Workers
844
+ * and Bun runtimes without Next-specific types being mandatory.
845
+ */
846
+ interface RequestNextOptions {
847
+ revalidate?: number | false;
848
+ tags?: string[];
849
+ }
584
850
 
585
851
  /** Fields every listing card must have — no JSX. */
586
852
  type ListingCardModel = {
@@ -670,6 +936,11 @@ declare function searchHrefUsesLegacyFilterQuery(href: string): boolean;
670
936
  declare function clearStagedPathFilters(current: SearchPathFilters, keepFilterIds?: readonly string[]): SearchPathFilters;
671
937
  declare function visibleSearchFilters(schema: SearchUi | null): SearchUiFilter[];
672
938
  declare function toolbarFilterIds(schema: SearchUi | null): string[];
939
+ /**
940
+ * The zero option's label is schema data: "Studio" only for
941
+ * `property_bedrooms`, "0" for the other count filters. Never derive it from
942
+ * `option.id`.
943
+ */
673
944
  declare function countOptionLabel(option: Pick<SearchUiOption, "label">): string;
674
945
  declare function countFacetChoices(options: SearchUiOption[] | undefined): Array<{
675
946
  id: string;
@@ -703,248 +974,6 @@ type SearchChromeModel = {
703
974
  };
704
975
  declare function searchChromeModel(schema: SearchUi | null, pathFilters: SearchPathFilters, locationNames?: LocationNameTables | null): SearchChromeModel;
705
976
 
706
- /**
707
- * Types for the maps.fndn.ai helpers (`./maps`). Everything here works on
708
- * the coordinates the public listings API already returns — those are
709
- * masked per site (≈100 m by default) and the helpers never add precision.
710
- */
711
-
712
- /** `{ lat, lng }` pair as returned on `listing.location.coordinates`. */
713
- interface MapsCoordinates {
714
- lat: number;
715
- lng: number;
716
- }
717
- /**
718
- * Anything carrying a public listing location: `Listing`, `ListingDetail`,
719
- * a card model, or a bare `{ location: { coordinates } }`.
720
- */
721
- type ListingWithLocation = {
722
- location?: {
723
- coordinates?: MapsCoordinates | null;
724
- } | null;
725
- } | null | undefined;
726
- interface MapsBaseOptions {
727
- /** maps.fndn.ai origin. Defaults to `https://maps.fndn.ai`. */
728
- mapsBaseUrl?: string;
729
- /**
730
- * Site id (or publishable key) used to meter this site's usage on
731
- * maps.fndn.ai. Sent as the `site` query param on image URLs and as the
732
- * `X-Garagem-Site` header on fetches. Optional today; it only labels
733
- * metrics and the per-site rate limit, it is not authentication.
734
- */
735
- siteId?: string;
736
- }
737
- interface MapsFetchOptions extends MapsBaseOptions {
738
- /** Override the fetch implementation (testing, edge runtimes, retries). */
739
- fetch?: FetchLike;
740
- }
741
- /** Google Static Maps map type. `style` is the SDK-facing alias. */
742
- type StaticMapStyle = "roadmap" | "satellite" | "terrain" | "hybrid";
743
- interface StaticMapOptions extends MapsBaseOptions {
744
- /** Pixels, 1–640 (Google Static Maps ceiling). Default 600. */
745
- width?: number;
746
- /** Pixels, 1–640. Default 300. */
747
- height?: number;
748
- /**
749
- * 1–21. Default 15. Capped by the coordinate precision the API applied:
750
- * a ≈100 m masked point is never rendered above zoom 16, so the pin does
751
- * not pretend to know the exact building. See `maxZoomForCoordinates`.
752
- */
753
- zoom?: number;
754
- /** 1 or 2 (retina). Default 2. */
755
- scale?: 1 | 2;
756
- /** Map style. Default roadmap. */
757
- style?: StaticMapStyle;
758
- /** Marker color (Google color name or `0xRRGGBB`). Default red. */
759
- markerColor?: string;
760
- /** Hide points of interest. Default false. */
761
- hidePoi?: boolean;
762
- /**
763
- * Max decimal places to send. Only ever *reduces* precision (e.g. send
764
- * 2 decimals ≈ 1 km for a neighbourhood teaser); it cannot recover
765
- * precision the API removed.
766
- */
767
- maxDecimals?: number;
768
- }
769
- interface StreetViewOptions extends MapsBaseOptions {
770
- /** Pixels, 1–640. Default 640. */
771
- width?: number;
772
- /** Pixels, 1–640. Default 640. */
773
- height?: number;
774
- /** Field of view in degrees, 10–120. Default 90. */
775
- fov?: number;
776
- /** Compass heading 0–360. Default 0. */
777
- heading?: number;
778
- /** Camera pitch -90–90. Default 10. */
779
- pitch?: number;
780
- /** See `StaticMapOptions.maxDecimals`. */
781
- maxDecimals?: number;
782
- }
783
- interface StreetViewAvailabilityOptions extends MapsFetchOptions {
784
- /** See `StaticMapOptions.maxDecimals`. */
785
- maxDecimals?: number;
786
- }
787
- interface StreetViewAvailability {
788
- /** `true` when Google has a panorama near the (masked) coordinates. */
789
- available: boolean;
790
- /** Google metadata status: `OK`, `ZERO_RESULTS`, `ERROR`, … */
791
- status: string;
792
- /** Panorama id when available. */
793
- panoId?: string;
794
- /** Capture date (`YYYY-MM`) when available. */
795
- date?: string;
796
- /** maps.fndn.ai metadata URL that was queried. */
797
- url: string;
798
- }
799
- /** Cities with boundary layers on maps.fndn.ai. Other slugs pass through. */
800
- type BoundaryCity = "sao_paulo" | "rio_de_janeiro" | (string & {});
801
- type BoundaryLayerUrlKind =
802
- /** `GET /v1/layers/:id` — layer descriptor JSON. */
803
- "layer"
804
- /** TileJSON for MapLibre `addSource({ type: "vector", url })`. */
805
- | "tilejson"
806
- /** `{z}/{x}/{y}` vector tile template. */
807
- | "tiles"
808
- /** Whole-city GeoJSON FeatureCollection. */
809
- | "geojson";
810
- interface BoundaryLayerOptions extends MapsBaseOptions {
811
- kind?: BoundaryLayerUrlKind;
812
- }
813
- interface BoundarySourceLayer {
814
- id: string;
815
- label: string;
816
- minzoom?: number;
817
- maxzoom?: number;
818
- }
819
- /** Subset of the maps.fndn.ai `/v1/layers/:id` descriptor the SDK exposes. */
820
- interface BoundaryLayer {
821
- id: string;
822
- name: string;
823
- description: string;
824
- city?: string;
825
- /** `{z}/{x}/{y}` template. */
826
- tiles: string;
827
- tilejson: string;
828
- /** Whole-city GeoJSON, when published. */
829
- geojson?: string;
830
- sourceLayers: BoundarySourceLayer[];
831
- minzoom: number;
832
- maxzoom: number;
833
- attribution?: string;
834
- available: boolean;
835
- }
836
- /** Minimal GeoJSON shapes so the SDK does not depend on `@types/geojson`. */
837
- interface BoundaryGeometry {
838
- type: string;
839
- coordinates: unknown;
840
- }
841
- interface BoundaryFeature {
842
- type: "Feature";
843
- properties: Record<string, unknown> & {
844
- name?: string;
845
- level?: string;
846
- };
847
- geometry: BoundaryGeometry | null;
848
- [key: string]: unknown;
849
- }
850
- interface BoundaryFeatureCollection {
851
- type: "FeatureCollection";
852
- features: BoundaryFeature[];
853
- count?: number;
854
- source?: string;
855
- }
856
- interface NeighborhoodBoundaryOptions extends MapsFetchOptions {
857
- /**
858
- * Boundary dataset. Default `listaaberta` (SP districts / RJ
859
- * neighbourhoods with IPTU stats); `osm` covers more cities.
860
- */
861
- source?: "listaaberta" | "osm" | "all";
862
- }
863
- interface NeighborhoodBoundary {
864
- city: string;
865
- neighborhood: string;
866
- /** The matched outline, or `null` when nothing matched. */
867
- feature: BoundaryFeature | null;
868
- /** Every candidate when the name matched more than one feature. */
869
- candidates: BoundaryFeature[];
870
- /** GeoJSON URL that was queried (safe to pass to MapLibre `data`). */
871
- url: string;
872
- /** Vector tile template for the city's boundary layer. */
873
- tiles: string;
874
- }
875
- type TravelMode = "driving" | "walking" | "bicycling" | "transit";
876
- /** Coordinates, or a free-text address geocoded on maps.fndn.ai first. */
877
- type TravelDestination = MapsCoordinates | string;
878
- interface TravelTimeOptions extends MapsFetchOptions {
879
- /** Default `driving`. */
880
- mode?: TravelMode;
881
- /** Client-side cache. Defaults to a module-level LRU; pass `null` to skip. */
882
- cache?: TravelTimeCache | null;
883
- /** See `StaticMapOptions.maxDecimals`. */
884
- maxDecimals?: number;
885
- }
886
- interface TravelTime {
887
- /** Rounded travel time in minutes (minimum 1 when a route exists). */
888
- minutes: number;
889
- seconds: number;
890
- distanceMeters: number;
891
- /** Distance rounded to one decimal. */
892
- distanceKm: number;
893
- mode: TravelMode;
894
- origin: MapsCoordinates;
895
- destination: MapsCoordinates;
896
- /** `true` when served from the client-side cache. */
897
- cached: boolean;
898
- }
899
- interface TravelTimesOptions extends MapsFetchOptions {
900
- /** See `StaticMapOptions.maxDecimals`. */
901
- maxDecimals?: number;
902
- }
903
- /** One route-matrix element; `null` when Google found no route. */
904
- interface TravelTimeElement {
905
- minutes: number;
906
- seconds: number;
907
- destination: MapsCoordinates;
908
- }
909
- interface TravelTimeCacheOptions {
910
- /** Default 200 entries. */
911
- maxEntries?: number;
912
- /** Default 15 minutes. */
913
- ttlMs?: number;
914
- }
915
- interface TravelTimeCache {
916
- get(key: string): TravelTime | undefined;
917
- set(key: string, value: TravelTime): void;
918
- clear(): void;
919
- readonly size: number;
920
- }
921
- /** Viewport rectangle in degrees. `east` must be greater than `west`. */
922
- interface MapBounds {
923
- north: number;
924
- south: number;
925
- east: number;
926
- west: number;
927
- }
928
- /** `[lat, lng]` vertices. Not GeoJSON `[lng, lat]`. */
929
- type MapPolygon = Array<[number, number]>;
930
- /** Pin plotted from a public listing. Coordinates are already masked. */
931
- interface MapPin {
932
- id: string;
933
- lat: number;
934
- lng: number;
935
- price: number | null;
936
- coverImage: string | null;
937
- }
938
- /** One grid cell. `count === 1` keeps the pin's own coordinates. */
939
- interface MapPinCluster {
940
- id: string;
941
- lat: number;
942
- lng: number;
943
- count: number;
944
- pinIds: string[];
945
- pin: MapPin | null;
946
- }
947
-
948
977
  /**
949
978
  * Map search on top of the friendly public listings route.
950
979
  *
@@ -955,6 +984,10 @@ interface MapPinCluster {
955
984
  *
956
985
  * Pins copy `listing.location.coordinates` as the API returned them.
957
986
  * Those values are already masked. Nothing here adds precision.
987
+ *
988
+ * When the matches do not fit on page 1, the route also returns weighted
989
+ * location buckets. Cluster those instead of the page's pins, so the
990
+ * badges add up to `total` rather than to one page.
958
991
  */
959
992
 
960
993
  /** Matches `FRIENDLY_SEARCH_MAX_LIMIT` on the public listings route. */
@@ -999,6 +1032,8 @@ interface MapSearchResult {
999
1032
  pageSize: number;
1000
1033
  total: number;
1001
1034
  totalPages: number;
1035
+ /** Empty when page 1 holds every match. */
1036
+ buckets: MapBucket[];
1002
1037
  }
1003
1038
  interface MapSearchSubscription extends MapSearchRequest {
1004
1039
  siteId: string;
@@ -1016,12 +1051,13 @@ declare function searchListingsInBounds(siteId: string, options: MapBoundsSearch
1016
1051
  declare function searchListingsInPolygon(siteId: string, options: MapPolygonSearchOptions): Promise<MapSearchResult>;
1017
1052
  /** Degrees per grid cell: a quarter of one world tile at this zoom. */
1018
1053
  declare function mapClusterCellDegrees(zoom: number): number;
1054
+ /** Headless grid cluster of one page of pins. */
1055
+ declare function clusterPins(pins: readonly MapPin[], zoom: number): MapPinCluster[];
1019
1056
  /**
1020
- * Headless grid cluster. A cell with one pin keeps that pin's coordinates.
1021
- * A group centroid is rounded to the members' own precision so clustering
1022
- * cannot invent extra decimals.
1057
+ * Grid cluster of location buckets. Counts add up, so a cell's badge is
1058
+ * the real total of its buckets. Bucket cells carry no pins.
1023
1059
  */
1024
- declare function clusterPins(pins: readonly MapPin[], zoom: number): MapPinCluster[];
1060
+ declare function clusterBuckets(buckets: readonly MapBucket[], zoom: number): MapPinCluster[];
1025
1061
 
1026
1062
  /**
1027
1063
  * "Busca pelo que as fotos mostram": search a site's catalog by what the
@@ -1073,4 +1109,4 @@ type ListingWithMatchedPhoto = Listing & {
1073
1109
  matchedPhoto: MatchedListingPhoto | null;
1074
1110
  };
1075
1111
 
1076
- export { type CmsEntryStatus as $, type AppliedSearchQuery as A, type BoundaryCity as B, type CmsCollection as C, type TravelMode as D, type TravelTimeOptions as E, type FetchLike as F, type TravelTime as G, type TravelTimesOptions as H, type TravelTimeElement as I, type Listing as J, type PhotoSearchResult as K, type ListingDetail as L, type MapsCoordinates as M, type NeighborhoodBoundaryOptions as N, type PhotoSearchItem as O, type PhotoSearchParams as P, type QueryListingsFilters as Q, type RequestNextOptions as R, type SearchPathFilters as S, type TravelTimeCacheOptions as T, type ListingWithMatchedPhoto as U, type MatchedListingPhoto as V, type BoundaryFeature as W, type BoundaryFeatureCollection as X, type BoundaryGeometry as Y, type BoundaryLayerUrlKind as Z, type BoundarySourceLayer as _, type ListingLocation as a, hrefWithExplicitPage as a$, type CmsFieldDefinition as a0, type CmsFieldType as a1, type CmsSeoData as a2, FORBIDDEN_SEARCH_QUERY_KEYS as a3, GaragemSdkError as a4, type GetCmsCollectionOptions as a5, type GetCmsCollectionsOptions as a6, type GetCmsEntriesOptions as a7, type GetCmsEntryOptions as a8, type GetListingOptions as a9, type SearchListingsOptions as aA, type SearchPathLocation as aB, type SearchUiFilter as aC, type SearchUiOption as aD, type StaticMapStyle as aE, TOOLBAR_PRIMARY_FILTER_IDS as aF, applyPathFilter as aG, buildQueryListingsParams as aH, canonicalizeSearchHref as aI, capMapPage as aJ, capMapPageSize as aK, clearStagedPathFilters as aL, clusterPins as aM, countFacetChoices as aN, countOptionLabel as aO, displayPathLocation as aP, getCmsCollection as aQ, getCmsCollections as aR, getCmsEntries as aS, getCmsEntry as aT, getListing as aU, getListings as aV, getSearchUi as aW, getSimilarListings as aX, getSite as aY, hrefForAppliedChange as aZ, hrefForPathFilters as a_, type GetListingsOptions as aa, type GetSearchUiOptions as ab, type GetSimilarListingsOptions as ac, type GetSiteOptions as ad, type ListingBusinessType as ae, type ListingCardModel as af, type ListingPriceVisibility as ag, type ListingPropertySummary as ah, type LocationNameTables as ai, MAP_POLYGON_MAX_VERTICES as aj, MAP_SEARCH_DEFAULT_PAGE_SIZE as ak, MAP_SEARCH_MAX_PAGE_SIZE as al, MAP_VIEWPORT_DEBOUNCE_MS as am, type MapBounds as an, type MapBoundsSearchOptions as ao, type MapPin as ap, type MapPinCluster as aq, type MapPolygon as ar, type MapPolygonSearchOptions as as, type MapSearchResult as at, type MapsBaseOptions as au, type QueryListingsLocation as av, type QueryListingsOptions as aw, SEARCH_EMPTY_COPY as ax, SEARCH_SORT_RELEVANCE as ay, type SearchChromeModel as az, type ListingMedia as b, isListingDetailPath as b0, isMapBounds as b1, isMapPolygon as b2, listingLocationLabel as b3, mapClusterCellDegrees as b4, mapSearchPins as b5, paginationPages as b6, pathFilterHasOption as b7, pathFilterValue as b8, publicSearchHref as b9, queryListings as ba, rangeDraftFromPath as bb, readPublicSearch as bc, searchChromeModel as bd, searchHrefUsesLegacyFilterQuery as be, searchListings as bf, searchListingsInBounds as bg, searchListingsInPolygon as bh, searchResultsHeading as bi, searchSortOptions as bj, toListingCardModel as bk, toolbarFilterIds as bl, visibleSearchFilters as bm, type MapSearchSubscription as bn, type SearchUiDictionary as c, type AppliedSearchChange as d, type ListingFilters as e, type ListingsResult as f, type Site as g, type SearchListingsParams as h, type SearchListingsResult as i, type SearchUi as j, type QueryListingsParams as k, type QueryListingsResult as l, type SimilarListingsResult as m, type CmsEntriesResult as n, type CmsEntry as o, type BoundaryLayerOptions as p, type TravelTimeCache as q, type MapsFetchOptions as r, type BoundaryLayer as s, type ListingWithLocation as t, type StaticMapOptions as u, type StreetViewAvailabilityOptions as v, type StreetViewAvailability as w, type StreetViewOptions as x, type NeighborhoodBoundary as y, type TravelDestination as z };
1112
+ export { type CmsEntryStatus as $, type AppliedSearchQuery as A, type BoundaryCity as B, type CmsCollection as C, type TravelMode as D, type TravelTimeOptions as E, type FetchLike as F, type TravelTime as G, type TravelTimesOptions as H, type TravelTimeElement as I, type Listing as J, type PhotoSearchResult as K, type ListingDetail as L, type MapsCoordinates as M, type NeighborhoodBoundaryOptions as N, type PhotoSearchItem as O, type PhotoSearchParams as P, type QueryListingsFilters as Q, type RequestNextOptions as R, type SearchPathFilters as S, type TravelTimeCacheOptions as T, type ListingWithMatchedPhoto as U, type MatchedListingPhoto as V, type BoundaryFeature as W, type BoundaryFeatureCollection as X, type BoundaryGeometry as Y, type BoundaryLayerUrlKind as Z, type BoundarySourceLayer as _, type ListingLocation as a, hrefForAppliedChange as a$, type CmsFieldDefinition as a0, type CmsFieldType as a1, type CmsSeoData as a2, FORBIDDEN_SEARCH_QUERY_KEYS as a3, GaragemSdkError as a4, type GetCmsCollectionOptions as a5, type GetCmsCollectionsOptions as a6, type GetCmsEntriesOptions as a7, type GetCmsEntryOptions as a8, type GetListingOptions as a9, type SearchChromeModel as aA, type SearchListingsOptions as aB, type SearchPathLocation as aC, type SearchUiFilter as aD, type SearchUiOption as aE, type StaticMapStyle as aF, TOOLBAR_PRIMARY_FILTER_IDS as aG, applyPathFilter as aH, buildQueryListingsParams as aI, canonicalizeSearchHref as aJ, capMapPage as aK, capMapPageSize as aL, clearStagedPathFilters as aM, clusterBuckets as aN, clusterPins as aO, countFacetChoices as aP, countOptionLabel as aQ, displayPathLocation as aR, getCmsCollection as aS, getCmsCollections as aT, getCmsEntries as aU, getCmsEntry as aV, getListing as aW, getListings as aX, getSearchUi as aY, getSimilarListings as aZ, getSite as a_, type GetListingsOptions as aa, type GetSearchUiOptions as ab, type GetSimilarListingsOptions as ac, type GetSiteOptions as ad, type ListingBusinessType as ae, type ListingCardModel as af, type ListingPriceVisibility as ag, type ListingPropertySummary as ah, type LocationNameTables as ai, MAP_POLYGON_MAX_VERTICES as aj, MAP_SEARCH_DEFAULT_PAGE_SIZE as ak, MAP_SEARCH_MAX_PAGE_SIZE as al, MAP_VIEWPORT_DEBOUNCE_MS as am, type MapBounds as an, type MapBoundsSearchOptions as ao, type MapBucket as ap, type MapPin as aq, type MapPinCluster as ar, type MapPolygon as as, type MapPolygonSearchOptions as at, type MapSearchResult as au, type MapsBaseOptions as av, type QueryListingsLocation as aw, type QueryListingsOptions as ax, SEARCH_EMPTY_COPY as ay, SEARCH_SORT_RELEVANCE as az, type ListingMedia as b, hrefForPathFilters as b0, hrefWithExplicitPage as b1, isListingDetailPath as b2, isMapBounds as b3, isMapPolygon as b4, listingLocationLabel as b5, mapClusterCellDegrees as b6, mapSearchPins as b7, paginationPages as b8, pathFilterHasOption as b9, pathFilterValue as ba, publicSearchHref as bb, queryListings as bc, rangeDraftFromPath as bd, readPublicSearch as be, searchChromeModel as bf, searchHrefUsesLegacyFilterQuery as bg, searchListings as bh, searchListingsInBounds as bi, searchListingsInPolygon as bj, searchResultsHeading as bk, searchSortOptions as bl, toListingCardModel as bm, toolbarFilterIds as bn, visibleSearchFilters as bo, type MapSearchSubscription as bp, type SearchUiDictionary as c, type AppliedSearchChange as d, type ListingFilters as e, type ListingsResult as f, type Site as g, type SearchListingsParams as h, type SearchListingsResult as i, type SearchUi as j, type QueryListingsParams as k, type QueryListingsResult as l, type SimilarListingsResult as m, type CmsEntriesResult as n, type CmsEntry as o, type BoundaryLayerOptions as p, type TravelTimeCache as q, type MapsFetchOptions as r, type BoundaryLayer as s, type ListingWithLocation as t, type StaticMapOptions as u, type StreetViewAvailabilityOptions as v, type StreetViewAvailability as w, type StreetViewOptions as x, type NeighborhoodBoundary as y, type TravelDestination as z };