@garagem-ai/site-sdk 0.6.0 → 0.7.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 CHANGED
@@ -95,6 +95,52 @@ All fetchers accept:
95
95
  - `fetch` — custom fetch implementation (testing, retries, edge runtimes).
96
96
  - `next: { revalidate, tags }` — forwarded directly to the underlying `fetch` for Next.js App Router caching. Ignored on runtimes that don't understand it.
97
97
 
98
+ ## Market data (IPTU module required)
99
+
100
+ Neighborhood price summary, listing market position, and a visitor price
101
+ estimate. **Every helper is a no-op unless the site's organization has the
102
+ IPTU module** (`iptu_itbi_integration`) and the city is covered. There is
103
+ no error status for that case: the call returns HTTP 200 with
104
+ `{ available: false, reason }`. Render the block only when `available` is
105
+ true; otherwise render nothing (no placeholder, no local fallback number).
106
+
107
+ The payloads are aggregates and a trimmed estimate. They never include
108
+ cadastral ids, IPTU lookups, ITBI transactions, comparables, or unit
109
+ inventory. Do not request or invent those fields.
110
+
111
+ | API | Description |
112
+ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
113
+ | `getNeighborhoodSummary({ siteId, query, next? })` | P25 / P50 / P75 price per m² and sample size for a neighborhood. `query` is `{ city, neighborhood, propertyType?, type? }`. `type: "rent"` answers `listing_type_unsupported` (sale only). Cache with `next: { revalidate: 900 }`. |
114
+ | `getListingMarketPosition({ siteId, listingId, next? })` | The listing's public price per m² versus the neighborhood median (`percentVsMedian`, `band`). Copy comes from `marketPositionLabel` / `priceBandLabel` (both return `null` when unavailable). |
115
+ | `requestPriceEstimate({ siteId, input })` | Trimmed estimate for visitor-entered characteristics (`city`, `areaSqm`, optional neighborhood, bedrooms, parking, property type). Rate limited per visitor. Call it from a submit handler, not on page load. |
116
+ | `marketPositionLabel(position)` | pt-BR line such as `8% abaixo da mediana do bairro`. |
117
+ | `priceBandLabel(position)` | pt-BR quartile line such as `Na faixa do bairro, abaixo da mediana`. |
118
+
119
+ `reason` is a code (`module_not_enabled`, `city_unsupported`, `no_data`,
120
+ `rate_limited`, …). Do not print it. When `available` is false, `message`
121
+ is already pt-BR and is only for the estimate form's empty state.
122
+
123
+ ```ts
124
+ import {
125
+ getListingMarketPosition,
126
+ getNeighborhoodSummary,
127
+ marketPositionLabel,
128
+ } from "@garagem-ai/site-sdk";
129
+
130
+ const summary = await getNeighborhoodSummary({
131
+ siteId,
132
+ query: { city: "São Paulo", neighborhood: "Moema" },
133
+ next: { revalidate: 900 },
134
+ });
135
+
136
+ if (summary.available) {
137
+ summary.pricePerSqmFormatted.p50; // "R$ 10.870,00/m²"
138
+ }
139
+
140
+ const position = await getListingMarketPosition({ siteId, listingId });
141
+ const label = marketPositionLabel(position); // null when the module is off
142
+ ```
143
+
98
144
  ## Similar listings example
99
145
 
100
146
  ```tsx
@@ -284,6 +330,51 @@ SEO stable: count `<span data-slot="search-heading-count">` first, then
284
330
  `<h1 data-slot="search-heading-title">`. Hit count is never inside
285
331
  `<h1>`.
286
332
 
333
+ ## Photo search ("busca pelo que as fotos mostram")
334
+
335
+ Search a site's public catalog by what the photos show, and use the photo
336
+ that matched as the card cover. The tenant gate is `available`: when photo
337
+ search is off, the API answers `200` with `{ available: false, items: [] }`
338
+ so the site hides the control and keeps the regular search.
339
+
340
+ ```ts
341
+ import {
342
+ applyMatchedPhotoCover,
343
+ searchListingPhotos,
344
+ } from "@garagem-ai/site-sdk";
345
+
346
+ const photos = await searchListingPhotos("abc-123", {
347
+ q: "varanda gourmet com churrasqueira",
348
+ limit: 12,
349
+ page: 1,
350
+ });
351
+
352
+ if (!photos.available) {
353
+ // Regular search. Do not show an empty photo-search state.
354
+ }
355
+
356
+ // Nearest first, cover already chosen by the API.
357
+ const cards = applyMatchedPhotoCover(
358
+ photos.items.map((item) => item.listing),
359
+ photos
360
+ );
361
+ // cards[i].coverImage is the matched photo; cards[i].matchedPhoto is set.
362
+ ```
363
+
364
+ On the client, `usePublicPhotoSearch` from `@garagem-ai/site-sdk/react`
365
+ debounces the search box (default 400ms) and returns `listings` with the
366
+ cover already swapped. Pass `enabled: false` while the toggle is off.
367
+ `photos.listings` when the toggle is on and `photos.available` is true;
368
+ otherwise the regular `usePublicSearch` results. A keyword match
369
+ (`distance: null`) always replaces the cover; a vector match replaces it
370
+ only within `MATCHED_PHOTO_COVER_MAX_DISTANCE` (0.4), the same threshold as
371
+ the CRM "Foto que combina com a busca" switch.
372
+
373
+ Each distinct query costs one text embedding on the Garagem side. Results
374
+ are cached for ten minutes per site and query, and uncached queries are
375
+ rate limited per visitor and per site. Queries shorter than three characters
376
+ resolve locally and do not hit the API.
377
+
287
378
  ## What's NOT in this release
288
379
 
289
380
  - CMS writes / drafts (editor + CMS worker only).
package/dist/index.d.mts CHANGED
@@ -1,151 +1,5 @@
1
- import { R as RequestNextOptions, L as ListingFilters, Q as QueryListingsParams, S as SearchListingsParams, C as CmsCollection, a as CmsEntriesResult, b as CmsEntry, c as ListingDetail, d as ListingsResult, e as SearchUi, f as SimilarListingsResult, g as Site, h as QueryListingsResult, i as SearchListingsResult, j as ListingLocation, k as ListingMedia, l as ListingBusinessType, m as ListingPriceVisibility, n as Listing, o as SearchPathFilters, p as SearchUiDictionary, q as QueryListingsFilters, A as AppliedSearchQuery, r as AppliedSearchChange } from './search-engine-CtnLzmwW.mjs';
2
- export { s as CmsEntryStatus, t as CmsFieldDefinition, u as CmsFieldType, v as CmsSeoData, F as FORBIDDEN_SEARCH_QUERY_KEYS, w as ListingPropertySummary, x as LocationNameTables, y as QueryListingsLocation, z as SEARCH_EMPTY_COPY, B as SEARCH_SORT_RELEVANCE, D as SearchChromeModel, E as SearchPathLocation, G as SearchUiFilter, H as SearchUiOption, T as TOOLBAR_PRIMARY_FILTER_IDS, I as applyPathFilter, J as buildQueryListingsParams, K as canonicalizeSearchHref, M as clearStagedPathFilters, N as countFacetChoices, O as countOptionLabel, P as displayPathLocation, U as hrefForAppliedChange, V as hrefForPathFilters, W as hrefWithExplicitPage, X as isListingDetailPath, Y as paginationPages, Z as pathFilterHasOption, _ as pathFilterValue, $ as publicSearchHref, a0 as rangeDraftFromPath, a1 as readPublicSearch, a2 as searchChromeModel, a3 as searchHrefUsesLegacyFilterQuery, a4 as searchResultsHeading, a5 as searchSortOptions, a6 as toolbarFilterIds, a7 as visibleSearchFilters } from './search-engine-CtnLzmwW.mjs';
3
-
4
- /** Custom fetch implementation. Defaults to the global `fetch`. */
5
- type FetchLike = typeof fetch;
6
- interface BaseOptions {
7
- /** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
8
- baseUrl?: string;
9
- /** Override the fetch implementation (testing, edge runtimes, retries). */
10
- fetch?: FetchLike;
11
- /**
12
- * Next.js App Router caching hints. Ignored on runtimes that don't
13
- * understand them.
14
- */
15
- next?: RequestNextOptions;
16
- }
17
- interface GetListingsOptions extends BaseOptions {
18
- siteId: string;
19
- filters?: ListingFilters;
20
- }
21
- interface GetListingOptions extends BaseOptions {
22
- siteId: string;
23
- listingId: string;
24
- }
25
- interface GetSiteOptions extends BaseOptions {
26
- /** Look up by site ID, or… */
27
- siteId?: string;
28
- /** …by domain. Exactly one of `siteId` / `domain` must be provided. */
29
- domain?: string;
30
- }
31
- interface SearchListingsOptions extends BaseOptions {
32
- siteId: string;
33
- params: SearchListingsParams;
34
- }
35
- interface GetSearchUiOptions extends BaseOptions {
36
- siteId: string;
37
- }
38
- interface QueryListingsOptions extends BaseOptions {
39
- siteId: string;
40
- params?: QueryListingsParams;
41
- }
42
- interface GetSimilarListingsOptions extends BaseOptions {
43
- siteId: string;
44
- listingId: string;
45
- /** Max similar cards to return (API default 6, cap 12). */
46
- limit?: number;
47
- }
48
- interface GetCmsCollectionsOptions extends BaseOptions {
49
- siteId: string;
50
- }
51
- interface GetCmsCollectionOptions extends BaseOptions {
52
- siteId: string;
53
- slug: string;
54
- }
55
- interface GetCmsEntriesOptions extends BaseOptions {
56
- siteId: string;
57
- collection: string;
58
- limit?: number;
59
- offset?: number;
60
- }
61
- interface GetCmsEntryOptions extends BaseOptions {
62
- siteId: string;
63
- collection: string;
64
- slug: string;
65
- }
66
- /** Error thrown when a fetcher hits a non-2xx response. */
67
- declare class GaragemSdkError extends Error {
68
- readonly status: number;
69
- readonly url: string;
70
- constructor(message: string, info: {
71
- status: number;
72
- url: string;
73
- });
74
- }
75
- /**
76
- * Fetch a paginated list of listings for a given site.
77
- *
78
- * @example
79
- * const { listings } = await getListings({
80
- * siteId: "abc",
81
- * filters: { city: "São Paulo", limit: 24 },
82
- * next: { revalidate: 300, tags: [`site:abc:listings`] },
83
- * });
84
- */
85
- declare function getListings(options: GetListingsOptions): Promise<ListingsResult>;
86
- /**
87
- * Fetch a single listing's full detail (amenities, gallery, building).
88
- * `listingId` accepts a code, UUID, or `id-{code}` URL segment.
89
- */
90
- declare function getListing(options: GetListingOptions): Promise<ListingDetail>;
91
- /**
92
- * Resolve a site's public profile by ID or by domain. Returns `null`
93
- * when the site does not exist or the host is unrecognized.
94
- *
95
- * @example
96
- * const site = await getSite({ domain: "imobiliariax.com.br" });
97
- * if (!site) return notFound();
98
- */
99
- declare function getSite(options: GetSiteOptions): Promise<Site | null>;
100
- /**
101
- * Advanced search escape hatch.
102
- *
103
- * Calls `POST /api/sites/{siteId}/search` directly and returns the raw
104
- * Typesense response (`{ found, page, hits: [{ document, ... }], ... }`).
105
- * Use when `queryListings` isn't expressive enough — faceted search,
106
- * multi-field sort, custom grouping, etc.
107
- *
108
- * @example
109
- * const result = await searchListings({
110
- * siteId: "abc",
111
- * params: {
112
- * q: "frente mar",
113
- * query_by: "title,description,neighborhood",
114
- * filter_by: "businessType:=sale && bedrooms:>=3",
115
- * sort_by: "price:asc",
116
- * per_page: 24,
117
- * page: 1,
118
- * facet_by: "neighborhood,propertyType",
119
- * },
120
- * });
121
- * for (const hit of result.hits) {
122
- * console.log(hit.document, hit.highlight);
123
- * }
124
- */
125
- declare function searchListings<TDocument = Record<string, unknown>>(options: SearchListingsOptions): Promise<SearchListingsResult<TDocument>>;
126
- /**
127
- * Tenant search schema: filters, slugs, sort tokens, defaultLimit 12.
128
- * Use this to render the search UI — do not hardcode property types.
129
- */
130
- declare function getSearchUi(options: GetSearchUiOptions): Promise<SearchUi>;
131
- /**
132
- * Friendly catalog search (editor combinators). Prefer this over
133
- * `searchListings` — that helper is a raw Typesense escape hatch.
134
- */
135
- declare function queryListings(options: QueryListingsOptions): Promise<QueryListingsResult>;
136
- /**
137
- * Fetch similar listings for a detail page carousel.
138
- * Returns an empty list when the reference listing is missing.
139
- */
140
- declare function getSimilarListings(options: GetSimilarListingsOptions): Promise<SimilarListingsResult>;
141
- /** List CMS collections for a site. */
142
- declare function getCmsCollections(options: GetCmsCollectionsOptions): Promise<CmsCollection[]>;
143
- /** Fetch one CMS collection schema by slug. */
144
- declare function getCmsCollection(options: GetCmsCollectionOptions): Promise<CmsCollection>;
145
- /** List published CMS entries for a collection. */
146
- declare function getCmsEntries(options: GetCmsEntriesOptions): Promise<CmsEntriesResult>;
147
- /** Fetch one published CMS entry by slug. */
148
- declare function getCmsEntry(options: GetCmsEntryOptions): Promise<CmsEntry>;
1
+ import { F as FetchLike, R as RequestNextOptions, L as ListingDetail, a as ListingLocation, b as ListingMedia, c as ListingBusinessType, d as ListingPriceVisibility, e as Listing, S as SearchPathFilters, f as SearchUiDictionary, Q as QueryListingsFilters, A as AppliedSearchQuery, g as AppliedSearchChange, h as ListingFilters, i as ListingsResult, j as Site, k as SearchListingsParams, l as SearchListingsResult, m as SearchUi, n as QueryListingsParams, o as QueryListingsResult, p as SimilarListingsResult, C as CmsCollection, q as CmsEntriesResult, r as CmsEntry, P as PhotoSearchParams, s as PhotoSearchResult, t as PhotoSearchItem, u as ListingWithMatchedPhoto, M as MatchedListingPhoto } from './types-photo-search-OeONNDxl.mjs';
2
+ export { v as CmsEntryStatus, w as CmsFieldDefinition, x as CmsFieldType, y as CmsSeoData, z as FORBIDDEN_SEARCH_QUERY_KEYS, G as GaragemSdkError, B as GetCmsCollectionOptions, D as GetCmsCollectionsOptions, E as GetCmsEntriesOptions, H as GetCmsEntryOptions, I as GetListingOptions, J as GetListingsOptions, K as GetSearchUiOptions, N as GetSimilarListingsOptions, O as GetSiteOptions, T as ListingPropertySummary, U as LocationNameTables, V as QueryListingsLocation, W as QueryListingsOptions, X as SEARCH_EMPTY_COPY, Y as SEARCH_SORT_RELEVANCE, Z as SearchChromeModel, _ as SearchListingsOptions, $ as SearchPathLocation, a0 as SearchUiFilter, a1 as SearchUiOption, a2 as TOOLBAR_PRIMARY_FILTER_IDS, a3 as applyPathFilter, a4 as buildQueryListingsParams, a5 as canonicalizeSearchHref, a6 as clearStagedPathFilters, a7 as countFacetChoices, a8 as countOptionLabel, a9 as displayPathLocation, aa as getCmsCollection, ab as getCmsCollections, ac as getCmsEntries, ad as getCmsEntry, ae as getListing, af as getListings, ag as getSearchUi, ah as getSimilarListings, ai as getSite, aj as hrefForAppliedChange, ak as hrefForPathFilters, al as hrefWithExplicitPage, am as isListingDetailPath, an as paginationPages, ao as pathFilterHasOption, ap as pathFilterValue, aq as publicSearchHref, ar as queryListings, as as rangeDraftFromPath, at as readPublicSearch, au as searchChromeModel, av as searchHrefUsesLegacyFilterQuery, aw as searchListings, ax as searchResultsHeading, ay as searchSortOptions, az as toolbarFilterIds, aA as visibleSearchFilters } from './types-photo-search-OeONNDxl.mjs';
149
3
 
150
4
  /**
151
5
  * Visit-lead schedule: hours in, slots out. Pure — no fetch, no React.
@@ -604,11 +458,13 @@ declare const STUDIO_SDK_CONTRACT: {
604
458
  * Exact pin for generated Studio sites. Must match a tarball already on
605
459
  * npm — v0 installs this version. After a later changeset publishes, bump
606
460
  * this and move that release's names from `optionalReactExports` /
607
- * `unpublishedSearchExports` into the prompt-safe lists. Do not bump here
608
- * until that tarball is on npm. Headless SearchPage already shipped in
609
- * 0.4.12 (`visibleSearchFilters` / `toolbarFilterIds` are on that pin).
461
+ * `unpublishedSearchExports` / `unpublishedPhoneExports` into the
462
+ * prompt-safe lists. Do not bump here until that tarball is on npm.
463
+ * Phone mask helpers shipped in 0.6.0. Search filter helpers
464
+ * (`visibleSearchFilters` / `toolbarFilterIds`) shipped in 0.4.12 and
465
+ * remain on this pin.
610
466
  */
611
- readonly minNpmVersion: "0.4.12";
467
+ readonly minNpmVersion: "0.6.0";
612
468
  /** Historical: older tarballs inject card CSS when those components mount. */
613
469
  readonly selfInjectSince: "0.4.2";
614
470
  readonly chromeStrategy: "app-owned";
@@ -635,24 +491,22 @@ declare const STUDIO_SDK_CONTRACT: {
635
491
  /** Main-package card helpers — markup stays in the generated app. */
636
492
  readonly listingCardExports: readonly ["toListingCardModel", "listingPublicPath", "formatAreaM2", "listingBusinessLabel", "formatListingPrice"];
637
493
  /**
638
- * Prompt-safe phone helpers on `minNpmVersion`. Empty until a published
639
- * tarball exports them and this pin bumps — then move names here from
640
- * `unpublishedPhoneExports`.
494
+ * Prompt-safe phone helpers on `minNpmVersion` (published in 0.6.0).
641
495
  */
642
- readonly phoneExports: readonly [];
496
+ readonly phoneExports: readonly ["PHONE_COUNTRIES", "formatPhoneNational", "toE164", "isValidPhone", "parsePhoneInput", "phoneCountrySearchValue", "findPhoneCountry", "remaskPhoneForCountry"];
643
497
  /**
644
- * Headless phone mask helpers in git / newer tarballs but not on
645
- * `minNpmVersion` (0.4.12). Prompts, completeness, and repair text must
646
- * not mention these until the pin bumps — v0 installs the pin and the
647
- * ESM loader throws on missing named exports.
498
+ * Headless phone helpers in git but not on `minNpmVersion`. Prompts,
499
+ * completeness, and repair text must not mention these until the pin
500
+ * bumps — v0 installs the pin and the ESM loader throws on missing
501
+ * named exports.
648
502
  */
649
- readonly unpublishedPhoneExports: readonly ["PHONE_COUNTRIES", "formatPhoneNational", "toE164", "isValidPhone", "parsePhoneInput", "phoneCountrySearchValue", "findPhoneCountry", "remaskPhoneForCountry"];
503
+ readonly unpublishedPhoneExports: readonly [];
650
504
  readonly amenityExports: readonly ["listingAmenityGroups"];
651
505
  /**
652
- * Names already on the pinned npm tarball (`minNpmVersion` / 0.4.12) —
653
- * safe for Studio prompts and completeness. Includes
654
- * `visibleSearchFilters` + `toolbarFilterIds` (shipped in 0.4.12). Do not
655
- * confuse with `unpublishedSearchExports` (`searchChromeModel`, …).
506
+ * Names already on the pinned npm tarball (`minNpmVersion`) — safe for
507
+ * Studio prompts and completeness. Includes `visibleSearchFilters` +
508
+ * `toolbarFilterIds` (shipped in 0.4.12). Do not confuse with
509
+ * `unpublishedSearchExports` (`searchChromeModel`, …).
656
510
  */
657
511
  readonly searchExports: readonly ["searchResultsHeading", "searchSortOptions", "visibleSearchFilters", "toolbarFilterIds", "paginationPages", "hrefWithExplicitPage"];
658
512
  /**
@@ -662,8 +516,33 @@ declare const STUDIO_SDK_CONTRACT: {
662
516
  * already listed in `searchExports`.
663
517
  */
664
518
  readonly unpublishedSearchExports: readonly ["searchChromeModel", "rangeDraftFromPath"];
519
+ /**
520
+ * Market-data helpers (neighborhood price summary, listing market
521
+ * position, visitor price estimate, pt-BR labels). They ship in
522
+ * `marketExportsSince` and are prompt-safe only once `minNpmVersion`
523
+ * reaches that release; below it `studioCodegenContractViolations` flags
524
+ * the names and `studioMarketInstruction()` tells Studio not to generate
525
+ * the blocks at all. Every helper answers `available: false` unless the
526
+ * site's organization holds the IPTU module (`iptu_itbi_integration`)
527
+ * and the city is covered — generated sites render these blocks
528
+ * conditionally and never show cadastral or transaction data.
529
+ */
530
+ readonly marketExports: readonly ["getNeighborhoodSummary", "getListingMarketPosition", "requestPriceEstimate", "marketPositionLabel", "priceBandLabel"];
531
+ readonly marketExportsSince: "0.7.0";
532
+ /**
533
+ * Photo search ("busca pelo que as fotos mostram"): main-package helpers
534
+ * that ship together with the `/react` hook listed in
535
+ * `optionalReactExports` (`usePublicPhotoSearch`). Prompt-safe only once
536
+ * `minNpmVersion` reaches `photoSearchSince` — `studioPhotoSearchInstruction`
537
+ * and the Studio guidance print nothing before that, and
538
+ * `studioCodegenContractViolations` flags the names until then.
539
+ */
540
+ readonly photoSearchExports: readonly ["searchListingPhotos", "applyMatchedPhotoCover"];
541
+ readonly photoSearchSince: "0.7.0";
665
542
  };
666
543
  type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
544
+ /** Whether the pinned tarball carries the photo-search surface. */
545
+ declare function isPhotoSearchOnPin(pin?: string): boolean;
667
546
  /**
668
547
  * Global Studio content width. Mirrors Editor default `7xl` / `px-4`
669
548
  * without the Marca picker — v0 sites are not `@garagem/ui`.
@@ -694,6 +573,20 @@ declare function studioListingCardInstruction(): string;
694
573
  declare function studioListingDetailInstruction(): string;
695
574
  declare function studioAmenityInstruction(): string;
696
575
  declare function studioSearchInstruction(): string;
576
+ /** True when the pinned tarball ships the market-data helpers. */
577
+ declare function marketExportsAvailableAt(pin: string): boolean;
578
+ /**
579
+ * Market-data blocks (neighborhood price summary, listing market position,
580
+ * visitor price estimate). Names appear only when the pin ships them; below
581
+ * that pin the instruction carries no identifiers (v0 copies any it sees).
582
+ */
583
+ declare function studioMarketInstruction(pin?: string): string;
584
+ /**
585
+ * Photo search ("busca pelo que as fotos mostram") codegen instruction.
586
+ * Empty until the pinned tarball ships the surface (`photoSearchSince`), so
587
+ * no prompt names an identifier v0 cannot import.
588
+ */
589
+ declare function studioPhotoSearchInstruction(pin?: string): string;
697
590
  declare function studioChromeInstruction(): string;
698
591
  /**
699
592
  * Tokens that must not appear in Studio codegen (prompts, recipes, repair).
@@ -809,4 +702,275 @@ interface GaragemClient {
809
702
  */
810
703
  declare function createGaragemClient(options?: CreateGaragemClientOptions): GaragemClient;
811
704
 
812
- export { AMENITY_FALLBACK_LABELS, type AmenityLabelDictionary, type AmenityLabelOption, AppliedSearchChange, AppliedSearchQuery, CmsCollection, CmsEntriesResult, CmsEntry, type ContactLeadInput, type CreateGaragemClientOptions, DEFAULT_PHONE_COUNTRY_CODE, type FetchLike, type GaragemClient, GaragemSdkError, type GetCmsCollectionOptions, type GetCmsCollectionsOptions, type GetCmsEntriesOptions, type GetCmsEntryOptions, type GetLeadUiOptions, type GetListingOptions, type GetListingsOptions, type GetSearchUiOptions, type GetSimilarListingsOptions, type GetSiteOptions, type HHmm, LISTING_AMENITY_TITLES, LISTING_DESCRIPTION_CLAMP, type LeadContact, type LeadField, type LeadFieldId, LeadSubmitError, type LeadSubmitErrorCode, type LeadSubmitResult, type LeadUi, Listing, type ListingAmenityGroup, type ListingAmenityGroupKey, type ListingAmenitySource, type ListingBreadcrumbCrumb, ListingBusinessType, type ListingCardModel, type ListingDescriptionPreview, ListingDetail, type ListingDetailFieldsModel, type ListingDetailFieldsSource, type ListingDetailModel, type ListingFact, ListingFilters, ListingLocation, type ListingLocationBlock, ListingMedia, type ListingMediaOverlay, ListingPriceVisibility, type ListingValue, ListingsResult, type LocationFilterInput, MAX_NATIONAL_PHONE_DIGITS, PHONE_COUNTRIES, type ParsedPhoneInput, type PhoneCountry, QueryListingsFilters, type QueryListingsOptions, QueryListingsParams, QueryListingsResult, RequestNextOptions, type ResolvePublicSiteIdOptions, STUDIO_DEFAULT_VISIT_SCHEDULE, STUDIO_SDK_CONTRACT, STUDIO_SDK_PACKAGE, STUDIO_SITE_LAYOUT, type SearchListingsOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, SimilarListingsResult, Site, type StudioSdkContract, VISIT_TIME_ZONE, type VisitHours, type VisitLeadInput, type VisitSchedule, type VisitScheduleConfig, coerceNpmVersion, collapseDuplicatedBrazilianMobileNine, compareSemver, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, defaultPhoneCountry, expandVisitSchedule, expandVisitTimeSlots, findPhoneCountry, formatAreaM2, formatGroupedInteger, formatListingPrice, formatPhoneNational, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getLeadUi, getListing, getListings, getSearchUi, getSimilarListings, getSite, hasShowcaseLeadsPostUrl, isStudioPreviewHost, isValidPhone, isVisitSlotAllowed, labelAmenities, listingAmenityGroups, listingBreadcrumb, listingBusinessLabel, listingDescriptionPreview, listingDetailFieldsModel, listingDetailModel, listingFacts, listingLocationBlock, listingLocationLabel, listingLookupKey, listingMapsHref, listingMediaOverlays, listingPublicPath, listingValues, mergeAppliedSearchQueryIntoSearch, nationalPhoneDigits, normalizeVisitDate, normalizeVisitTime, parseAppliedSearchQuery, parseGroupedInteger, parsePhoneInput, parseReactSdkNamedImports, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, phoneCountrySearchValue, queryListings, reduceAppliedSearchQuery, remaskPhoneForCountry, resolvePublicSiteId, searchListings, serializeAppliedSearchQuery, slotsForDate, studioAmenityInstruction, studioChromeInstruction, studioCodegenContractViolations, studioDefaultLeadUi, studioLayoutInstruction, studioLeadInstruction, studioListingCardInstruction, studioListingDetailInstruction, studioSdkPinInstruction, studioSearchInstruction, studioSearchLandmarkInstruction, studioSiteWidthCss, submitContactLead, submitVisitLead, toE164, toListingCardModel, truncateNationalPhoneDigits, unavailableReactImports };
705
+ /**
706
+ * Market-data types for the public site.
707
+ *
708
+ * IPTU-module requirement: every market endpoint answers
709
+ * `{ available: false, reason }` (HTTP 200) unless the site's organization
710
+ * holds the IPTU module (`iptu_itbi_integration`), the city is covered and
711
+ * the integration is configured. Render these blocks conditionally on
712
+ * `available`. The payloads carry only aggregates and the trimmed estimate —
713
+ * never comparables, transactions or cadastral identifiers.
714
+ */
715
+ /** Why a market helper answered `available: false`. */
716
+ type MarketUnavailableReason =
717
+ /** The organization does not hold the IPTU module (`iptu_itbi_integration`). */
718
+ "module_not_enabled"
719
+ /** Market-data integration is not configured for this environment. */
720
+ | "not_configured"
721
+ /** The site id does not resolve to an active site. */
722
+ | "site_not_found"
723
+ /** The city is outside the covered-city matrix. */
724
+ | "city_unsupported"
725
+ /** Only sale prices are covered. */
726
+ | "listing_type_unsupported"
727
+ /** Listing price is private or missing. */
728
+ | "price_unavailable"
729
+ /** No usable aggregate for the request. */
730
+ | "no_data"
731
+ /** The SDK was rate limited (HTTP 429); try again later. */
732
+ | "rate_limited";
733
+ type MarketPropertyType = "apartment" | "house";
734
+ type MarketListingType = "sale" | "rent";
735
+ interface NeighborhoodSummaryQuery {
736
+ /** City name or code (`"São Paulo"`, `"sp"`). */
737
+ city: string;
738
+ neighborhood: string;
739
+ /** Echoed back; the aggregate covers every property kind today. */
740
+ propertyType?: MarketPropertyType;
741
+ /** Defaults to `"sale"`; `"rent"` answers `listing_type_unsupported`. */
742
+ type?: MarketListingType;
743
+ }
744
+ interface NeighborhoodSummary {
745
+ available: boolean;
746
+ reason: MarketUnavailableReason | null;
747
+ /** Normalized city code (`sp` / `rj` / `bh`) when supported. */
748
+ city: string;
749
+ neighborhood: string;
750
+ propertyType: MarketPropertyType | null;
751
+ type: MarketListingType;
752
+ /** Lookback window in months. */
753
+ months: number;
754
+ /** Centavos per m². */
755
+ pricePerSqmCents: {
756
+ p25: number | null;
757
+ p50: number | null;
758
+ p75: number | null;
759
+ };
760
+ /** Pre-formatted `R$ X/m²` strings (`"—"` when missing). */
761
+ pricePerSqmFormatted: {
762
+ p25: string;
763
+ p50: string;
764
+ p75: string;
765
+ };
766
+ sampleSize: number | null;
767
+ /** pt-BR copy when unavailable. */
768
+ message: string | null;
769
+ }
770
+ /**
771
+ * Where a listing sits against the neighborhood quartiles:
772
+ * - `below_range`: under P25
773
+ * - `lower_range`: P25 ≤ price/m² < P50
774
+ * - `upper_range`: P50 ≤ price/m² ≤ P75
775
+ * - `above_range`: over P75
776
+ */
777
+ type MarketPriceBand = "below_range" | "lower_range" | "upper_range" | "above_range";
778
+ interface ListingMarketPosition {
779
+ available: boolean;
780
+ reason: MarketUnavailableReason | null;
781
+ listingId: string;
782
+ city: string | null;
783
+ neighborhood: string | null;
784
+ months: number;
785
+ /** Listing asking price per m², centavos. */
786
+ listingPricePerSqmCents: number | null;
787
+ listingPricePerSqmFormatted: string;
788
+ /** Neighborhood median (P50) price per m², centavos. */
789
+ medianPricePerSqmCents: number | null;
790
+ medianPricePerSqmFormatted: string;
791
+ /** Rounded percent vs the median; negative = below the median. */
792
+ percentVsMedian: number | null;
793
+ band: MarketPriceBand | null;
794
+ sampleSize: number | null;
795
+ message: string | null;
796
+ }
797
+ interface PriceEstimateInput {
798
+ /** City name or code (`"São Paulo"`, `"sp"`). */
799
+ city: string;
800
+ neighborhood?: string;
801
+ street?: string;
802
+ streetNumber?: string;
803
+ /** 8 digits, no dash. */
804
+ postalCode?: string;
805
+ /** m², 10–10000. */
806
+ areaSqm: number;
807
+ bedrooms?: number;
808
+ bathrooms?: number;
809
+ parkingSpots?: number;
810
+ propertyType?: MarketPropertyType;
811
+ listingType?: MarketListingType;
812
+ }
813
+ type PriceEstimateConfidence = "high" | "medium" | "low";
814
+ interface PriceEstimate {
815
+ available: boolean;
816
+ reason: MarketUnavailableReason | null;
817
+ city: string;
818
+ neighborhood: string | null;
819
+ estimatedPriceCents: number | null;
820
+ estimatedPriceFormatted: string;
821
+ rangeLowCents: number | null;
822
+ rangeHighCents: number | null;
823
+ rangeLowFormatted: string;
824
+ rangeHighFormatted: string;
825
+ confidenceLabel: PriceEstimateConfidence | null;
826
+ sampleSize: number | null;
827
+ /** pt-BR copy when unavailable. */
828
+ message: string | null;
829
+ }
830
+
831
+ /**
832
+ * Market-data fetchers for the public site.
833
+ *
834
+ * Requires the IPTU module: every call answers `{ available: false, reason }`
835
+ * unless the site's organization holds `iptu_itbi_integration`, the city
836
+ * is covered and the integration is configured. Render nothing in that
837
+ * case. A rate-limited call (HTTP 429) also comes back as
838
+ * `available: false` with `reason: "rate_limited"` instead of throwing, so
839
+ * a block can stay hidden without a try/catch; other non-2xx responses
840
+ * throw `GaragemSdkError` like the rest of the SDK.
841
+ */
842
+
843
+ interface MarketBaseOptions {
844
+ /** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
845
+ baseUrl?: string;
846
+ /** Override the fetch implementation (testing, edge runtimes, retries). */
847
+ fetch?: FetchLike;
848
+ /** Next.js App Router caching hints. Ignored elsewhere. */
849
+ next?: RequestNextOptions;
850
+ }
851
+ interface GetNeighborhoodSummaryOptions extends MarketBaseOptions {
852
+ siteId: string;
853
+ query: NeighborhoodSummaryQuery;
854
+ }
855
+ interface GetListingMarketPositionOptions extends MarketBaseOptions {
856
+ siteId: string;
857
+ /** Accepts a code, UUID, or `id-{code}` URL segment. */
858
+ listingId: string;
859
+ }
860
+ interface RequestPriceEstimateOptions extends MarketBaseOptions {
861
+ siteId: string;
862
+ input: PriceEstimateInput;
863
+ }
864
+ /**
865
+ * P25 / P50 / P75 price per m² and sample size for a neighborhood.
866
+ *
867
+ * @example
868
+ * const summary = await getNeighborhoodSummary({
869
+ * siteId,
870
+ * query: { city: "São Paulo", neighborhood: "Moema" },
871
+ * next: { revalidate: 900 },
872
+ * });
873
+ * if (summary.available) render(summary.pricePerSqmFormatted.p50);
874
+ */
875
+ declare function getNeighborhoodSummary(options: GetNeighborhoodSummaryOptions): Promise<NeighborhoodSummary>;
876
+ /**
877
+ * The listing's price per m² vs the neighborhood median, computed
878
+ * server-side from the public listing and the neighborhood summary.
879
+ *
880
+ * @example
881
+ * const position = await getListingMarketPosition({ siteId, listingId });
882
+ * const label = marketPositionLabel(position); // "8% abaixo da mediana do bairro"
883
+ */
884
+ declare function getListingMarketPosition(options: GetListingMarketPositionOptions): Promise<ListingMarketPosition>;
885
+ /**
886
+ * Trimmed automated valuation (estimate, range, confidence) for
887
+ * visitor-entered characteristics. Never returns comparables.
888
+ *
889
+ * Limited per IP and per site; a limited call answers
890
+ * `reason: "rate_limited"`.
891
+ *
892
+ * @example
893
+ * const estimate = await requestPriceEstimate({
894
+ * siteId,
895
+ * input: { city: "sp", neighborhood: "Moema", areaSqm: 80, bedrooms: 2 },
896
+ * });
897
+ */
898
+ declare function requestPriceEstimate(options: RequestPriceEstimateOptions): Promise<PriceEstimate>;
899
+
900
+ /**
901
+ * Headless pt-BR labels for the market-data blocks. Every helper returns
902
+ * `null` when there is nothing to say (unavailable, missing numbers), so a
903
+ * component can `label && <p>{label}</p>` without re-checking `available`.
904
+ */
905
+
906
+ /**
907
+ * "8% abaixo da mediana do bairro" / "12% acima da mediana do bairro" /
908
+ * "Na mediana do bairro". `null` when the position is unavailable.
909
+ */
910
+ declare function marketPositionLabel(position: Pick<ListingMarketPosition, "available" | "percentVsMedian"> | null | undefined): string | null;
911
+ /**
912
+ * Quartile band copy. Accepts the band itself or a position; `null` when
913
+ * the band is missing or the position is unavailable.
914
+ */
915
+ declare function priceBandLabel(input: MarketPriceBand | Pick<ListingMarketPosition, "available" | "band"> | null | undefined): string | null;
916
+
917
+ interface SearchListingPhotosOptions {
918
+ /** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
919
+ baseUrl?: string;
920
+ /** Override the fetch implementation (testing, edge runtimes, retries). */
921
+ fetch?: FetchLike;
922
+ /** Next.js App Router caching hints. Ignored on other runtimes. */
923
+ next?: RequestNextOptions;
924
+ }
925
+ /** Shortest query the API will embed; shorter text returns the empty result locally. */
926
+ declare const PHOTO_SEARCH_MIN_QUERY_LENGTH = 3;
927
+ /** Build the request URL (exported for tests and custom transports). */
928
+ declare function photoSearchUrl(siteId: string, params: PhotoSearchParams, baseUrl?: string): string;
929
+ /**
930
+ * Search a site's listings by what their public photos show.
931
+ *
932
+ * Returns `{ available: false, items: [] }` (not an error) when the tenant
933
+ * has not enabled photo search, so a site can hide the control. Queries
934
+ * shorter than {@link PHOTO_SEARCH_MIN_QUERY_LENGTH} resolve locally to an
935
+ * empty result without a request.
936
+ *
937
+ * @example
938
+ * const result = await searchListingPhotos("abc", { q: "varanda gourmet" });
939
+ * const cards = applyMatchedPhotoCover(
940
+ * result.items.map((item) => item.listing),
941
+ * result
942
+ * );
943
+ */
944
+ declare function searchListingPhotos(siteId: string, params: PhotoSearchParams, options?: SearchListingPhotosOptions): Promise<PhotoSearchResult>;
945
+
946
+ /**
947
+ * Largest vector distance a photo may have and still replace the cover.
948
+ * Mirrors the CRM "Foto que combina com a busca" threshold
949
+ * (`MATCHED_PHOTO_COVER_MAX_DISTANCE` in apps/foundation); keyword matches
950
+ * (`distance: null`) are exact caption / room-type matches and always win.
951
+ */
952
+ declare const MATCHED_PHOTO_COVER_MAX_DISTANCE = 0.4;
953
+ interface ApplyMatchedPhotoCoverOptions {
954
+ /** Override {@link MATCHED_PHOTO_COVER_MAX_DISTANCE}. `Infinity` accepts every match. */
955
+ maxDistance?: number;
956
+ }
957
+ /**
958
+ * The photo that replaces a card cover, or `null` to keep the card's own
959
+ * cover: keyword matches as-is, vector matches only within `maxDistance`.
960
+ */
961
+ declare function resolveMatchedCoverPhoto(photo: MatchedListingPhoto | null | undefined, maxDistance?: number): MatchedListingPhoto | null;
962
+ /**
963
+ * Headless mirror of the CRM cover switch: for every card whose listing has
964
+ * a photo-search match, swap `coverImage` for the matched photo and attach
965
+ * it as `matchedPhoto`. Cards without a match (or whose match is too far)
966
+ * keep their cover with `matchedPhoto: null`. Order is preserved — pass
967
+ * `result.items.map((item) => item.listing)` to render the photo-search
968
+ * page nearest-first, or the regular search page to only swap covers.
969
+ *
970
+ * @example
971
+ * const cards = applyMatchedPhotoCover(search.listings, photos.items);
972
+ * cards.map((card) => <Card model={toListingCardModel(card)} badge={card.matchedPhoto} />)
973
+ */
974
+ declare function applyMatchedPhotoCover<T extends Listing>(cards: ReadonlyArray<T>, photoResults: PhotoSearchResult | ReadonlyArray<PhotoSearchItem> | null | undefined, options?: ApplyMatchedPhotoCoverOptions): Array<T & ListingWithMatchedPhoto>;
975
+
976
+ export { AMENITY_FALLBACK_LABELS, type AmenityLabelDictionary, type AmenityLabelOption, AppliedSearchChange, AppliedSearchQuery, type ApplyMatchedPhotoCoverOptions, CmsCollection, CmsEntriesResult, CmsEntry, type ContactLeadInput, type CreateGaragemClientOptions, DEFAULT_PHONE_COUNTRY_CODE, FetchLike, type GaragemClient, type GetLeadUiOptions, type GetListingMarketPositionOptions, type GetNeighborhoodSummaryOptions, type HHmm, LISTING_AMENITY_TITLES, LISTING_DESCRIPTION_CLAMP, type LeadContact, type LeadField, type LeadFieldId, LeadSubmitError, type LeadSubmitErrorCode, type LeadSubmitResult, type LeadUi, Listing, type ListingAmenityGroup, type ListingAmenityGroupKey, type ListingAmenitySource, type ListingBreadcrumbCrumb, ListingBusinessType, type ListingCardModel, type ListingDescriptionPreview, ListingDetail, type ListingDetailFieldsModel, type ListingDetailFieldsSource, type ListingDetailModel, type ListingFact, ListingFilters, ListingLocation, type ListingLocationBlock, type ListingMarketPosition, ListingMedia, type ListingMediaOverlay, ListingPriceVisibility, type ListingValue, ListingWithMatchedPhoto, ListingsResult, type LocationFilterInput, MATCHED_PHOTO_COVER_MAX_DISTANCE, MAX_NATIONAL_PHONE_DIGITS, type MarketListingType, type MarketPriceBand, type MarketPropertyType, type MarketUnavailableReason, MatchedListingPhoto, type NeighborhoodSummary, type NeighborhoodSummaryQuery, PHONE_COUNTRIES, PHOTO_SEARCH_MIN_QUERY_LENGTH, type ParsedPhoneInput, type PhoneCountry, PhotoSearchItem, PhotoSearchParams, PhotoSearchResult, type PriceEstimate, type PriceEstimateConfidence, type PriceEstimateInput, QueryListingsFilters, QueryListingsParams, QueryListingsResult, RequestNextOptions, type RequestPriceEstimateOptions, type ResolvePublicSiteIdOptions, STUDIO_DEFAULT_VISIT_SCHEDULE, STUDIO_SDK_CONTRACT, STUDIO_SDK_PACKAGE, STUDIO_SITE_LAYOUT, type SearchListingPhotosOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, SimilarListingsResult, Site, type StudioSdkContract, VISIT_TIME_ZONE, type VisitHours, type VisitLeadInput, type VisitSchedule, type VisitScheduleConfig, applyMatchedPhotoCover, coerceNpmVersion, collapseDuplicatedBrazilianMobileNine, compareSemver, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, defaultPhoneCountry, expandVisitSchedule, expandVisitTimeSlots, findPhoneCountry, formatAreaM2, formatGroupedInteger, formatListingPrice, formatPhoneNational, getLeadUi, getListingMarketPosition, getNeighborhoodSummary, hasShowcaseLeadsPostUrl, isPhotoSearchOnPin, isStudioPreviewHost, isValidPhone, isVisitSlotAllowed, labelAmenities, listingAmenityGroups, listingBreadcrumb, listingBusinessLabel, listingDescriptionPreview, listingDetailFieldsModel, listingDetailModel, listingFacts, listingLocationBlock, listingLocationLabel, listingLookupKey, listingMapsHref, listingMediaOverlays, listingPublicPath, listingValues, marketExportsAvailableAt, marketPositionLabel, mergeAppliedSearchQueryIntoSearch, nationalPhoneDigits, normalizeVisitDate, normalizeVisitTime, parseAppliedSearchQuery, parseGroupedInteger, parsePhoneInput, parseReactSdkNamedImports, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, phoneCountrySearchValue, photoSearchUrl, priceBandLabel, reduceAppliedSearchQuery, remaskPhoneForCountry, requestPriceEstimate, resolveMatchedCoverPhoto, resolvePublicSiteId, searchListingPhotos, serializeAppliedSearchQuery, slotsForDate, studioAmenityInstruction, studioChromeInstruction, studioCodegenContractViolations, studioDefaultLeadUi, studioLayoutInstruction, studioLeadInstruction, studioListingCardInstruction, studioListingDetailInstruction, studioMarketInstruction, studioPhotoSearchInstruction, studioSdkPinInstruction, studioSearchInstruction, studioSearchLandmarkInstruction, studioSiteWidthCss, submitContactLead, submitVisitLead, toE164, toListingCardModel, truncateNationalPhoneDigits, unavailableReactImports };