@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/dist/index.js CHANGED
@@ -27,8 +27,10 @@ __export(src_exports, {
27
27
  LISTING_AMENITY_TITLES: () => LISTING_AMENITY_TITLES,
28
28
  LISTING_DESCRIPTION_CLAMP: () => LISTING_DESCRIPTION_CLAMP,
29
29
  LeadSubmitError: () => LeadSubmitError,
30
+ MATCHED_PHOTO_COVER_MAX_DISTANCE: () => MATCHED_PHOTO_COVER_MAX_DISTANCE,
30
31
  MAX_NATIONAL_PHONE_DIGITS: () => MAX_NATIONAL_PHONE_DIGITS,
31
32
  PHONE_COUNTRIES: () => PHONE_COUNTRIES,
33
+ PHOTO_SEARCH_MIN_QUERY_LENGTH: () => PHOTO_SEARCH_MIN_QUERY_LENGTH,
32
34
  SEARCH_EMPTY_COPY: () => SEARCH_EMPTY_COPY,
33
35
  SEARCH_SORT_RELEVANCE: () => SEARCH_SORT_RELEVANCE,
34
36
  STUDIO_DEFAULT_VISIT_SCHEDULE: () => STUDIO_DEFAULT_VISIT_SCHEDULE,
@@ -37,6 +39,7 @@ __export(src_exports, {
37
39
  STUDIO_SITE_LAYOUT: () => STUDIO_SITE_LAYOUT,
38
40
  TOOLBAR_PRIMARY_FILTER_IDS: () => TOOLBAR_PRIMARY_FILTER_IDS,
39
41
  VISIT_TIME_ZONE: () => VISIT_TIME_ZONE,
42
+ applyMatchedPhotoCover: () => applyMatchedPhotoCover,
40
43
  applyPathFilter: () => applyPathFilter,
41
44
  buildQueryListingsParams: () => buildQueryListingsParams,
42
45
  canonicalizeSearchHref: () => canonicalizeSearchHref,
@@ -64,7 +67,9 @@ __export(src_exports, {
64
67
  getCmsEntry: () => getCmsEntry,
65
68
  getLeadUi: () => getLeadUi,
66
69
  getListing: () => getListing,
70
+ getListingMarketPosition: () => getListingMarketPosition,
67
71
  getListings: () => getListings,
72
+ getNeighborhoodSummary: () => getNeighborhoodSummary,
68
73
  getSearchUi: () => getSearchUi,
69
74
  getSimilarListings: () => getSimilarListings,
70
75
  getSite: () => getSite,
@@ -73,6 +78,7 @@ __export(src_exports, {
73
78
  hrefForPathFilters: () => hrefForPathFilters,
74
79
  hrefWithExplicitPage: () => hrefWithExplicitPage,
75
80
  isListingDetailPath: () => isListingDetailPath,
81
+ isPhotoSearchOnPin: () => isPhotoSearchOnPin,
76
82
  isStudioPreviewHost: () => isStudioPreviewHost,
77
83
  isValidPhone: () => isValidPhone,
78
84
  isVisitSlotAllowed: () => isVisitSlotAllowed,
@@ -91,6 +97,8 @@ __export(src_exports, {
91
97
  listingMediaOverlays: () => listingMediaOverlays,
92
98
  listingPublicPath: () => listingPublicPath,
93
99
  listingValues: () => listingValues,
100
+ marketExportsAvailableAt: () => marketExportsAvailableAt,
101
+ marketPositionLabel: () => marketPositionLabel,
94
102
  mergeAppliedSearchQueryIntoSearch: () => mergeAppliedSearchQueryIntoSearch2,
95
103
  nationalPhoneDigits: () => nationalPhoneDigits,
96
104
  normalizeVisitDate: () => normalizeVisitDate,
@@ -106,15 +114,20 @@ __export(src_exports, {
106
114
  pathFiltersToQueryFilters: () => pathFiltersToQueryFilters,
107
115
  pathLocationToFilterInput: () => pathLocationToFilterInput,
108
116
  phoneCountrySearchValue: () => phoneCountrySearchValue,
117
+ photoSearchUrl: () => photoSearchUrl,
118
+ priceBandLabel: () => priceBandLabel,
109
119
  publicSearchHref: () => publicSearchHref,
110
120
  queryListings: () => queryListings,
111
121
  rangeDraftFromPath: () => rangeDraftFromPath,
112
122
  readPublicSearch: () => readPublicSearch,
113
123
  reduceAppliedSearchQuery: () => reduceAppliedSearchQuery2,
114
124
  remaskPhoneForCountry: () => remaskPhoneForCountry,
125
+ requestPriceEstimate: () => requestPriceEstimate,
126
+ resolveMatchedCoverPhoto: () => resolveMatchedCoverPhoto,
115
127
  resolvePublicSiteId: () => resolvePublicSiteId,
116
128
  searchChromeModel: () => searchChromeModel,
117
129
  searchHrefUsesLegacyFilterQuery: () => searchHrefUsesLegacyFilterQuery,
130
+ searchListingPhotos: () => searchListingPhotos,
118
131
  searchListings: () => searchListings,
119
132
  searchResultsHeading: () => searchResultsHeading,
120
133
  searchSortOptions: () => searchSortOptions,
@@ -128,6 +141,8 @@ __export(src_exports, {
128
141
  studioLeadInstruction: () => studioLeadInstruction,
129
142
  studioListingCardInstruction: () => studioListingCardInstruction,
130
143
  studioListingDetailInstruction: () => studioListingDetailInstruction,
144
+ studioMarketInstruction: () => studioMarketInstruction,
145
+ studioPhotoSearchInstruction: () => studioPhotoSearchInstruction,
131
146
  studioSdkPinInstruction: () => studioSdkPinInstruction,
132
147
  studioSearchInstruction: () => studioSearchInstruction,
133
148
  studioSearchLandmarkInstruction: () => studioSearchLandmarkInstruction,
@@ -2733,11 +2748,13 @@ var STUDIO_SDK_CONTRACT = {
2733
2748
  * Exact pin for generated Studio sites. Must match a tarball already on
2734
2749
  * npm — v0 installs this version. After a later changeset publishes, bump
2735
2750
  * this and move that release's names from `optionalReactExports` /
2736
- * `unpublishedSearchExports` into the prompt-safe lists. Do not bump here
2737
- * until that tarball is on npm. Headless SearchPage already shipped in
2738
- * 0.4.12 (`visibleSearchFilters` / `toolbarFilterIds` are on that pin).
2751
+ * `unpublishedSearchExports` / `unpublishedPhoneExports` into the
2752
+ * prompt-safe lists. Do not bump here until that tarball is on npm.
2753
+ * Phone mask helpers shipped in 0.6.0. Search filter helpers
2754
+ * (`visibleSearchFilters` / `toolbarFilterIds`) shipped in 0.4.12 and
2755
+ * remain on this pin.
2739
2756
  */
2740
- minNpmVersion: "0.4.12",
2757
+ minNpmVersion: "0.6.0",
2741
2758
  /** Historical: older tarballs inject card CSS when those components mount. */
2742
2759
  selfInjectSince: "0.4.2",
2743
2760
  chromeStrategy: "app-owned",
@@ -2749,7 +2766,9 @@ var STUDIO_SDK_CONTRACT = {
2749
2766
  * “never import”) — v0 copies the identifier and the preview ESM loader
2750
2767
  * throws FatalRendererError.
2751
2768
  */
2752
- optionalReactExports: {},
2769
+ optionalReactExports: {
2770
+ usePublicPhotoSearch: "0.7.0"
2771
+ },
2753
2772
  /**
2754
2773
  * Former `/react` chrome (including card/skeleton inject). Completeness
2755
2774
  * flags imports as mismatch (not in `reactExports`). Prompts must not
@@ -2790,18 +2809,9 @@ var STUDIO_SDK_CONTRACT = {
2790
2809
  "formatListingPrice"
2791
2810
  ],
2792
2811
  /**
2793
- * Prompt-safe phone helpers on `minNpmVersion`. Empty until a published
2794
- * tarball exports them and this pin bumps — then move names here from
2795
- * `unpublishedPhoneExports`.
2812
+ * Prompt-safe phone helpers on `minNpmVersion` (published in 0.6.0).
2796
2813
  */
2797
- phoneExports: [],
2798
- /**
2799
- * Headless phone mask helpers in git / newer tarballs but not on
2800
- * `minNpmVersion` (0.4.12). Prompts, completeness, and repair text must
2801
- * not mention these until the pin bumps — v0 installs the pin and the
2802
- * ESM loader throws on missing named exports.
2803
- */
2804
- unpublishedPhoneExports: [
2814
+ phoneExports: [
2805
2815
  "PHONE_COUNTRIES",
2806
2816
  "formatPhoneNational",
2807
2817
  "toE164",
@@ -2811,12 +2821,19 @@ var STUDIO_SDK_CONTRACT = {
2811
2821
  "findPhoneCountry",
2812
2822
  "remaskPhoneForCountry"
2813
2823
  ],
2824
+ /**
2825
+ * Headless phone helpers in git but not on `minNpmVersion`. Prompts,
2826
+ * completeness, and repair text must not mention these until the pin
2827
+ * bumps — v0 installs the pin and the ESM loader throws on missing
2828
+ * named exports.
2829
+ */
2830
+ unpublishedPhoneExports: [],
2814
2831
  amenityExports: ["listingAmenityGroups"],
2815
2832
  /**
2816
- * Names already on the pinned npm tarball (`minNpmVersion` / 0.4.12) —
2817
- * safe for Studio prompts and completeness. Includes
2818
- * `visibleSearchFilters` + `toolbarFilterIds` (shipped in 0.4.12). Do not
2819
- * confuse with `unpublishedSearchExports` (`searchChromeModel`, …).
2833
+ * Names already on the pinned npm tarball (`minNpmVersion`) — safe for
2834
+ * Studio prompts and completeness. Includes `visibleSearchFilters` +
2835
+ * `toolbarFilterIds` (shipped in 0.4.12). Do not confuse with
2836
+ * `unpublishedSearchExports` (`searchChromeModel`, …).
2820
2837
  */
2821
2838
  searchExports: [
2822
2839
  "searchResultsHeading",
@@ -2835,8 +2852,43 @@ var STUDIO_SDK_CONTRACT = {
2835
2852
  unpublishedSearchExports: [
2836
2853
  "searchChromeModel",
2837
2854
  "rangeDraftFromPath"
2838
- ]
2855
+ ],
2856
+ /**
2857
+ * Market-data helpers (neighborhood price summary, listing market
2858
+ * position, visitor price estimate, pt-BR labels). They ship in
2859
+ * `marketExportsSince` and are prompt-safe only once `minNpmVersion`
2860
+ * reaches that release; below it `studioCodegenContractViolations` flags
2861
+ * the names and `studioMarketInstruction()` tells Studio not to generate
2862
+ * the blocks at all. Every helper answers `available: false` unless the
2863
+ * site's organization holds the IPTU module (`iptu_itbi_integration`)
2864
+ * and the city is covered — generated sites render these blocks
2865
+ * conditionally and never show cadastral or transaction data.
2866
+ */
2867
+ marketExports: [
2868
+ "getNeighborhoodSummary",
2869
+ "getListingMarketPosition",
2870
+ "requestPriceEstimate",
2871
+ "marketPositionLabel",
2872
+ "priceBandLabel"
2873
+ ],
2874
+ marketExportsSince: "0.7.0",
2875
+ /**
2876
+ * Photo search ("busca pelo que as fotos mostram"): main-package helpers
2877
+ * that ship together with the `/react` hook listed in
2878
+ * `optionalReactExports` (`usePublicPhotoSearch`). Prompt-safe only once
2879
+ * `minNpmVersion` reaches `photoSearchSince` — `studioPhotoSearchInstruction`
2880
+ * and the Studio guidance print nothing before that, and
2881
+ * `studioCodegenContractViolations` flags the names until then.
2882
+ */
2883
+ photoSearchExports: [
2884
+ "searchListingPhotos",
2885
+ "applyMatchedPhotoCover"
2886
+ ],
2887
+ photoSearchSince: "0.7.0"
2839
2888
  };
2889
+ function isPhotoSearchOnPin(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
2890
+ return compareSemver(pin, STUDIO_SDK_CONTRACT.photoSearchSince) >= 0;
2891
+ }
2840
2892
  var STUDIO_SITE_LAYOUT = {
2841
2893
  maxWidthRem: "80rem",
2842
2894
  maxWidthRemOptions: ["64rem", "80rem", "120rem", "160rem", "240rem"],
@@ -2922,12 +2974,13 @@ function unavailableReactImports(source, pin) {
2922
2974
  }
2923
2975
  function studioSdkPinInstruction() {
2924
2976
  const version = STUDIO_SDK_CONTRACT.minNpmVersion;
2925
- const names = STUDIO_SDK_CONTRACT.reactExports.join(", ");
2977
+ const names = [...reactExportsAvailableAt(version)].join(", ");
2926
2978
  return `In \`package.json\` set \`"@garagem-ai/site-sdk": "${version}"\` (exact). Import only these \`${STUDIO_SDK_PACKAGE}/react\` names: ${names}.`;
2927
2979
  }
2928
2980
  function studioLeadInstruction() {
2929
2981
  const names = STUDIO_SDK_CONTRACT.leadExports.join(", ");
2930
- return `Listing-detail visit/contact leads: import ${names} from \`${STUDIO_SDK_PACKAGE}\` (the main package, not \`/react\`). Call \`submitVisitLead\` / \`submitContactLead\` \u2014 never concatenate a leads webhook URL and never POST the Showcase demo leads route. Phone fields use a national mask with a country picker and submit E.164 \u2014 do not invent a second mask and do not import \`@garagem/ui\` PhoneInput.`;
2982
+ const phone = STUDIO_SDK_CONTRACT.phoneExports.join(", ");
2983
+ return `Listing-detail visit/contact leads: import ${names} from \`${STUDIO_SDK_PACKAGE}\` (the main package, not \`/react\`). Call \`submitVisitLead\` / \`submitContactLead\` \u2014 never concatenate a leads webhook URL and never POST the Showcase demo leads route. Phone fields: import ${phone} from the same package. Display draft is \`formatPhoneNational\` (default country \`BR\`); changing country calls \`remaskPhoneForCountry\`; submit \`toE164\` and require \`isValidPhone\`. Do not invent a second mask and do not import \`@garagem/ui\` PhoneInput.`;
2931
2984
  }
2932
2985
  function studioListingCardInstruction() {
2933
2986
  const names = STUDIO_SDK_CONTRACT.listingCardExports.join(", ");
@@ -2945,6 +2998,27 @@ function studioSearchInstruction() {
2945
2998
  const libNames = STUDIO_SDK_CONTRACT.searchExports.join(", ");
2946
2999
  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()\` \u2014 never shorthand \`{ search }\` beside \`const search =\` (temporal dead zone). Do not wrap this UI in \`<Suspense>\` and do not add a route \`loading\` file \u2014 heading and cards are ordinary elements in the document, visible with JavaScript off. Compose the page UI in the app \u2014 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)\` \u2014 never \`searchResultsHeading({})\`), toolbar (\`toolbarFilterIds\` + \`applyFilter\`; range \u201CAtualizar\u201D on that toolbar item only) vs sheet (\`visibleSearchFilters\` extras, \`stageFilter\`, one footer \`applyStaged\`), sort (\`searchSortOptions\` + \`setSort\`; first option id is \`""\` / \u201CMais relevantes\u201D \u2014 map **only** that empty id to Select sentinel \`"relevancia"\` (\`opt.id || "relevancia"\`), never \`SelectItem value=""\` and never give \u201CMais recentes\u201D (\`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 (\u201CMais relevantes\u201D when \`ordenar\` is absent), chevron at the end, same height as the toolbar controls. Toolbar ranges open a Popover form (not DropdownMenu \u2014 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\xE7o 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\xF3vel, caracter\xEDsticas and comodidades each use a nested ScrollArea with \`h-56 overflow-hidden\` (viewport \`h-full\`). Area is two inputs in schema order with no \u201CAplicar\u201D; the footer stages then applyStaged. Never read \`staged[filter.id]\` \u2014 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 \u2014 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)}`;
2947
3000
  }
3001
+ function marketExportsAvailableAt(pin) {
3002
+ return compareSemver(pin, STUDIO_SDK_CONTRACT.marketExportsSince) >= 0;
3003
+ }
3004
+ function studioMarketInstruction(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
3005
+ if (!marketExportsAvailableAt(pin)) {
3006
+ return `Market data (neighborhood price summary, listing market position, visitor price estimate): NOT available on this SDK pin. Do not generate these blocks and do not invent a local price index. **IPTU module required.** These blocks exist only for a site whose organization holds the IPTU module (\`iptu_itbi_integration\`); without it every helper answers \`{ available: false }\` (HTTP 200) and the section must not render \u2014 omit the heading too. Even when the module is on, the payload is aggregates and a trimmed estimate only: never show cadastral ids, IPTU lookups, ITBI transactions, comparables, or unit inventory.`;
3007
+ }
3008
+ const [summary, position, estimate, positionLabel, bandLabel] = STUDIO_SDK_CONTRACT.marketExports;
3009
+ const names = STUDIO_SDK_CONTRACT.marketExports.join(", ");
3010
+ return `Market data: import ${names} from \`${STUDIO_SDK_PACKAGE}\`. **IPTU module required.** Every helper returns \`{ available: false, reason }\` (HTTP 200, never a throw) unless the site's organization has the IPTU module (\`iptu_itbi_integration\`) and the city is covered \u2014 most sites get \`available: false\`. ALWAYS render these blocks conditionally: \`if (!result.available) return null\` (omit the whole section, heading included); never a placeholder, never \u201Cdados indispon\xEDveis\u201D, never a local fallback number. The payloads carry only aggregates and a trimmed estimate \u2014 never render, request, or invent cadastral ids, IPTU lookups, ITBI transactions, comparables, or addresses from market data. Reasons are codes (\`module_not_enabled\`, \`city_unsupported\`, \`no_data\`, \`rate_limited\`, \u2026) \u2014 do not print them. Three blocks (all optional, design is free):
3011
+ - Neighborhood summary (listing detail, optionally search heading): \`const summary = await ${summary}({ siteId, baseUrl: GARAGEM_API_BASE, query: { city: listing.location.city, neighborhood: listing.location.neighborhood } })\`. Render \`summary.pricePerSqmFormatted.p25\` / \`.p50\` / \`.p75\` (strings, already \`R$ X/m\xB2\`) and \`summary.sampleSize\` (\u201Ccom base em N vendas\u201D); omit the sample line when null.
3012
+ - Listing market position (listing detail, near the price): \`const position = await ${position}({ siteId, baseUrl: GARAGEM_API_BASE, listingId: listing.id })\`. Copy comes from the helpers only: \`${positionLabel}(position)\` (\u201C8% abaixo da mediana do bairro\u201D) and \`${bandLabel}(position)\` (\u201CNa faixa do bairro, abaixo da mediana\u201D); both return \`null\` when unavailable \u2014 hide the line on \`null\`. Show \`position.listingPricePerSqmFormatted\` vs \`position.medianPricePerSqmFormatted\` if a comparison row is wanted. Do not compute the percent in the app.
3013
+ - Visitor price estimate (\`/anunciar\` or a dedicated page, client component): a form with city, bairro, \xE1rea (m\xB2), quartos, vagas, tipo; on submit \`const estimate = await ${estimate}({ siteId, baseUrl: GARAGEM_API_BASE, input: { city, neighborhood, areaSqm, bedrooms, parkingSpots, propertyType } })\`. Render \`estimate.estimatedPriceFormatted\` with the range \`estimate.rangeLowFormatted\` \u2013 \`estimate.rangeHighFormatted\` and \`estimate.confidenceLabel\` mapped to pt-BR (alta / m\xE9dia / baixa). When \`available\` is false show \`estimate.message\` (pt-BR, already written) and the contact CTA. It is rate limited per visitor \u2014 disable the submit while pending. Never call it on page load.
3014
+ Fetch on the server page (\`next: { revalidate: 900 }\`) for the summary and position; the estimate is a user action. Resolve \`siteId\` the same way as every other SDK call.`;
3015
+ }
3016
+ function studioPhotoSearchInstruction(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
3017
+ if (!isPhotoSearchOnPin(pin)) return "";
3018
+ const hook = "usePublicPhotoSearch";
3019
+ const [fetcher, cover] = STUDIO_SDK_CONTRACT.photoSearchExports;
3020
+ return `Photo search (optional, same page as \`/imoveis\`): visitors can search by what the photos show ("varanda gourmet com churrasqueira"). From \`${STUDIO_SDK_PACKAGE}/react\` import ${hook}; from \`${STUDIO_SDK_PACKAGE}\` import ${fetcher} (server) and ${cover}. Client: \`const photos = ${hook}({ siteId, baseUrl: GARAGEM_API_BASE, query: search.qDraft, enabled: photoMode })\` where \`photoMode\` is a toggle beside the search box ("Buscar pelas fotos"). When \`photos.available === false\` do not render that toggle and keep the regular \`usePublicSearch\` results \u2014 the tenant has no photo lane. When it is on and \`photos.query\` is non-empty, render \`photos.listings\` (nearest first, cover already swapped, \`card.matchedPhoto\` for a small "Combina com a busca" badge) through the site listing-card module instead of \`search.listings\`; while \`photos.loading\` keep the previous cards. Fall back to the regular search results whenever \`photos.items\` is empty or \`photos.error\` is set. To only swap covers on the regular grid, \`${cover}(search.listings, photos.items)\` keeps the grid order and attaches \`matchedPhoto\`. Server pages use \`${fetcher}(siteId, { q, limit, page }, { baseUrl })\`. Cost: every distinct query costs one embedding on the Garagem side (results are cached ten minutes per site and query, and uncached queries are rate limited per visitor and per site), so never call it on every keystroke without the hook's debounce and never for the empty query.`;
3021
+ }
2948
3022
  function studioChromeInstruction() {
2949
3023
  return `Card, skeleton, and search chrome markup are app-owned. Never \`import "${STUDIO_SDK_CONTRACT.forbiddenImports[0]}"\` \u2014 v0 preview cannot load npm CSS. Do not mount an SDK stylesheet. Theme with site tokens and \`--radius\` in \`app/globals.css\`.`;
2950
3024
  }
@@ -2953,7 +3027,10 @@ function mentionsExportName(text, name) {
2953
3027
  }
2954
3028
  function studioCodegenContractViolations(text) {
2955
3029
  const violations = [];
2956
- for (const name of Object.keys(STUDIO_SDK_CONTRACT.optionalReactExports)) {
3030
+ for (const [name, since] of Object.entries(
3031
+ STUDIO_SDK_CONTRACT.optionalReactExports
3032
+ )) {
3033
+ if (compareSemver(STUDIO_SDK_CONTRACT.minNpmVersion, since) >= 0) continue;
2957
3034
  if (mentionsExportName(text, name)) violations.push(name);
2958
3035
  }
2959
3036
  for (const name of STUDIO_SDK_CONTRACT.retiredReactExports) {
@@ -2971,7 +3048,21 @@ function studioCodegenContractViolations(text) {
2971
3048
  violations.push(name);
2972
3049
  }
2973
3050
  }
3051
+ if (!isPhotoSearchOnPin()) {
3052
+ for (const name of STUDIO_SDK_CONTRACT.photoSearchExports) {
3053
+ if (mentionsExportName(text, name) && !violations.includes(name)) {
3054
+ violations.push(name);
3055
+ }
3056
+ }
3057
+ }
2974
3058
  const pin = STUDIO_SDK_CONTRACT.minNpmVersion;
3059
+ if (!marketExportsAvailableAt(pin)) {
3060
+ for (const name of STUDIO_SDK_CONTRACT.marketExports) {
3061
+ if (mentionsExportName(text, name) && !violations.includes(name)) {
3062
+ violations.push(name);
3063
+ }
3064
+ }
3065
+ }
2975
3066
  const available = reactExportsAvailableAt(pin);
2976
3067
  for (const name of parseReactSdkNamedImports(text)) {
2977
3068
  if (!available.has(name) && !violations.includes(name)) {
@@ -3142,6 +3233,241 @@ function createGaragemClient(options = {}) {
3142
3233
  }
3143
3234
  };
3144
3235
  }
3236
+
3237
+ // src/fetchers-market.ts
3238
+ var RATE_LIMITED_MESSAGE = "Muitas consultas em pouco tempo. Tente novamente em instantes.";
3239
+ function isRateLimited(error) {
3240
+ return error instanceof GaragemSdkError && error.status === 429;
3241
+ }
3242
+ async function getNeighborhoodSummary(options) {
3243
+ const { query, baseUrl, fetch: fetchImpl, next } = options;
3244
+ const siteId = await coerceSiteId(options.siteId);
3245
+ if (!query?.city?.trim() || !query?.neighborhood?.trim()) {
3246
+ throw new TypeError(
3247
+ "getNeighborhoodSummary: `query.city` and `query.neighborhood` are required"
3248
+ );
3249
+ }
3250
+ const base = normalizeBaseUrl(baseUrl);
3251
+ const params = new URLSearchParams();
3252
+ params.set("city", query.city.trim());
3253
+ params.set("neighborhood", query.neighborhood.trim());
3254
+ if (query.propertyType) params.set("propertyType", query.propertyType);
3255
+ if (query.type) params.set("type", query.type);
3256
+ const url = `${base}/api/sites/${encodeURIComponent(siteId)}/market/neighborhood-summary?${params.toString()}`;
3257
+ try {
3258
+ return await callJson(
3259
+ url,
3260
+ { method: "GET", headers: { Accept: "application/json" }, next },
3261
+ fetchImpl ?? fetch
3262
+ );
3263
+ } catch (error) {
3264
+ if (!isRateLimited(error)) throw error;
3265
+ return {
3266
+ available: false,
3267
+ reason: "rate_limited",
3268
+ city: query.city,
3269
+ neighborhood: query.neighborhood,
3270
+ propertyType: query.propertyType ?? null,
3271
+ type: query.type ?? "sale",
3272
+ months: 12,
3273
+ pricePerSqmCents: { p25: null, p50: null, p75: null },
3274
+ pricePerSqmFormatted: { p25: "\u2014", p50: "\u2014", p75: "\u2014" },
3275
+ sampleSize: null,
3276
+ message: RATE_LIMITED_MESSAGE
3277
+ };
3278
+ }
3279
+ }
3280
+ async function getListingMarketPosition(options) {
3281
+ const { listingId: rawListingId, baseUrl, fetch: fetchImpl, next } = options;
3282
+ const siteId = await coerceSiteId(options.siteId);
3283
+ const listingId = listingLookupKey(rawListingId ?? "");
3284
+ if (!listingId || listingId === "undefined" || listingId === "null") {
3285
+ throw new TypeError("getListingMarketPosition: `listingId` is required");
3286
+ }
3287
+ const base = normalizeBaseUrl(baseUrl);
3288
+ const url = `${base}/api/sites/${encodeURIComponent(siteId)}/listings/${encodeURIComponent(
3289
+ listingId
3290
+ )}/market-position`;
3291
+ try {
3292
+ return await callJson(
3293
+ url,
3294
+ { method: "GET", headers: { Accept: "application/json" }, next },
3295
+ fetchImpl ?? fetch
3296
+ );
3297
+ } catch (error) {
3298
+ if (!isRateLimited(error)) throw error;
3299
+ return {
3300
+ available: false,
3301
+ reason: "rate_limited",
3302
+ listingId,
3303
+ city: null,
3304
+ neighborhood: null,
3305
+ months: 12,
3306
+ listingPricePerSqmCents: null,
3307
+ listingPricePerSqmFormatted: "\u2014",
3308
+ medianPricePerSqmCents: null,
3309
+ medianPricePerSqmFormatted: "\u2014",
3310
+ percentVsMedian: null,
3311
+ band: null,
3312
+ sampleSize: null,
3313
+ message: RATE_LIMITED_MESSAGE
3314
+ };
3315
+ }
3316
+ }
3317
+ async function requestPriceEstimate(options) {
3318
+ const { input, baseUrl, fetch: fetchImpl, next } = options;
3319
+ const siteId = await coerceSiteId(options.siteId);
3320
+ if (!input?.city?.trim() || typeof input.areaSqm !== "number") {
3321
+ throw new TypeError(
3322
+ "requestPriceEstimate: `input.city` and `input.areaSqm` are required"
3323
+ );
3324
+ }
3325
+ const base = normalizeBaseUrl(baseUrl);
3326
+ const url = `${base}/api/sites/${encodeURIComponent(siteId)}/market/estimate`;
3327
+ try {
3328
+ return await callJson(
3329
+ url,
3330
+ {
3331
+ method: "POST",
3332
+ headers: {
3333
+ Accept: "application/json",
3334
+ "Content-Type": "application/json"
3335
+ },
3336
+ body: JSON.stringify(input),
3337
+ next
3338
+ },
3339
+ fetchImpl ?? fetch
3340
+ );
3341
+ } catch (error) {
3342
+ if (!isRateLimited(error)) throw error;
3343
+ return {
3344
+ available: false,
3345
+ reason: "rate_limited",
3346
+ city: input.city,
3347
+ neighborhood: input.neighborhood ?? null,
3348
+ estimatedPriceCents: null,
3349
+ estimatedPriceFormatted: "\u2014",
3350
+ rangeLowCents: null,
3351
+ rangeHighCents: null,
3352
+ rangeLowFormatted: "\u2014",
3353
+ rangeHighFormatted: "\u2014",
3354
+ confidenceLabel: null,
3355
+ sampleSize: null,
3356
+ message: RATE_LIMITED_MESSAGE
3357
+ };
3358
+ }
3359
+ }
3360
+
3361
+ // src/market-labels.ts
3362
+ function marketPositionLabel(position) {
3363
+ if (!position?.available) return null;
3364
+ const percent = position.percentVsMedian;
3365
+ if (percent == null || !Number.isFinite(percent)) return null;
3366
+ const rounded = Math.round(percent);
3367
+ if (rounded === 0) return "Na mediana do bairro";
3368
+ const magnitude = Math.abs(rounded);
3369
+ return rounded < 0 ? `${magnitude}% abaixo da mediana do bairro` : `${magnitude}% acima da mediana do bairro`;
3370
+ }
3371
+ var BAND_LABELS = {
3372
+ below_range: "Abaixo da faixa do bairro",
3373
+ lower_range: "Na faixa do bairro, abaixo da mediana",
3374
+ upper_range: "Na faixa do bairro, acima da mediana",
3375
+ above_range: "Acima da faixa do bairro"
3376
+ };
3377
+ function priceBandLabel(input) {
3378
+ if (!input) return null;
3379
+ if (typeof input === "string") return BAND_LABELS[input] ?? null;
3380
+ if (!input.available || !input.band) return null;
3381
+ return BAND_LABELS[input.band] ?? null;
3382
+ }
3383
+
3384
+ // src/fetchers-photo-search.ts
3385
+ var PHOTO_SEARCH_MIN_QUERY_LENGTH = 3;
3386
+ var EMPTY_RESULT = {
3387
+ available: true,
3388
+ items: [],
3389
+ total: 0,
3390
+ page: 1,
3391
+ limit: 12
3392
+ };
3393
+ function positiveInt(value) {
3394
+ if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
3395
+ return null;
3396
+ }
3397
+ return Math.floor(value);
3398
+ }
3399
+ function photoSearchUrl(siteId, params, baseUrl) {
3400
+ const search = new URLSearchParams();
3401
+ search.set("q", params.q.trim());
3402
+ const limit = positiveInt(params.limit);
3403
+ if (limit != null) search.set("limit", String(limit));
3404
+ const page = positiveInt(params.page);
3405
+ if (page != null) search.set("page", String(page));
3406
+ return `${normalizeBaseUrl(baseUrl)}/api/sites/${encodeURIComponent(
3407
+ siteId
3408
+ )}/search/photos?${search.toString()}`;
3409
+ }
3410
+ async function searchListingPhotos(siteId, params, options = {}) {
3411
+ const q = (params?.q ?? "").trim();
3412
+ const limit = positiveInt(params?.limit) ?? EMPTY_RESULT.limit;
3413
+ if (q.length < PHOTO_SEARCH_MIN_QUERY_LENGTH) {
3414
+ return { ...EMPTY_RESULT, limit, page: positiveInt(params?.page) ?? 1 };
3415
+ }
3416
+ const resolvedSiteId = await coerceSiteId(siteId);
3417
+ const url = photoSearchUrl(resolvedSiteId, { ...params, q }, options.baseUrl);
3418
+ const data = await callJson(
3419
+ url,
3420
+ {
3421
+ method: "GET",
3422
+ headers: { Accept: "application/json" },
3423
+ next: options.next
3424
+ },
3425
+ options.fetch ?? fetch
3426
+ );
3427
+ const items = Array.isArray(data.items) ? data.items : [];
3428
+ return {
3429
+ available: data.available !== false,
3430
+ items,
3431
+ total: typeof data.total === "number" ? data.total : items.length,
3432
+ page: typeof data.page === "number" ? data.page : positiveInt(params.page) ?? 1,
3433
+ limit: typeof data.limit === "number" ? data.limit : limit
3434
+ };
3435
+ }
3436
+
3437
+ // src/photo-search-cover.ts
3438
+ var MATCHED_PHOTO_COVER_MAX_DISTANCE = 0.4;
3439
+ function resolveMatchedCoverPhoto(photo, maxDistance = MATCHED_PHOTO_COVER_MAX_DISTANCE) {
3440
+ if (!photo || !photo.src) return null;
3441
+ if (photo.distance == null) return photo;
3442
+ if (!Number.isFinite(photo.distance)) return null;
3443
+ return photo.distance <= maxDistance ? photo : null;
3444
+ }
3445
+ function itemsOf(photoResults) {
3446
+ if (!photoResults) return [];
3447
+ return Array.isArray(photoResults) ? photoResults : photoResults.items ?? [];
3448
+ }
3449
+ function applyMatchedPhotoCover(cards, photoResults, options = {}) {
3450
+ const maxDistance = options.maxDistance ?? MATCHED_PHOTO_COVER_MAX_DISTANCE;
3451
+ const photoByListingId = /* @__PURE__ */ new Map();
3452
+ for (const item of itemsOf(photoResults)) {
3453
+ const id = item?.listing?.id;
3454
+ if (!id || photoByListingId.has(id)) continue;
3455
+ const photo = resolveMatchedCoverPhoto(item.matchedPhoto, maxDistance);
3456
+ if (photo) photoByListingId.set(id, photo);
3457
+ }
3458
+ return cards.map((card) => {
3459
+ const photo = photoByListingId.get(card.id) ?? null;
3460
+ if (!photo) return { ...card, matchedPhoto: null };
3461
+ return {
3462
+ ...card,
3463
+ coverImage: {
3464
+ src: photo.src,
3465
+ alt: photo.alt || card.coverImage?.alt || card.title
3466
+ },
3467
+ matchedPhoto: photo
3468
+ };
3469
+ });
3470
+ }
3145
3471
  // Annotate the CommonJS export names for ESM import in node:
3146
3472
  0 && (module.exports = {
3147
3473
  AMENITY_FALLBACK_LABELS,
@@ -3151,8 +3477,10 @@ function createGaragemClient(options = {}) {
3151
3477
  LISTING_AMENITY_TITLES,
3152
3478
  LISTING_DESCRIPTION_CLAMP,
3153
3479
  LeadSubmitError,
3480
+ MATCHED_PHOTO_COVER_MAX_DISTANCE,
3154
3481
  MAX_NATIONAL_PHONE_DIGITS,
3155
3482
  PHONE_COUNTRIES,
3483
+ PHOTO_SEARCH_MIN_QUERY_LENGTH,
3156
3484
  SEARCH_EMPTY_COPY,
3157
3485
  SEARCH_SORT_RELEVANCE,
3158
3486
  STUDIO_DEFAULT_VISIT_SCHEDULE,
@@ -3161,6 +3489,7 @@ function createGaragemClient(options = {}) {
3161
3489
  STUDIO_SITE_LAYOUT,
3162
3490
  TOOLBAR_PRIMARY_FILTER_IDS,
3163
3491
  VISIT_TIME_ZONE,
3492
+ applyMatchedPhotoCover,
3164
3493
  applyPathFilter,
3165
3494
  buildQueryListingsParams,
3166
3495
  canonicalizeSearchHref,
@@ -3188,7 +3517,9 @@ function createGaragemClient(options = {}) {
3188
3517
  getCmsEntry,
3189
3518
  getLeadUi,
3190
3519
  getListing,
3520
+ getListingMarketPosition,
3191
3521
  getListings,
3522
+ getNeighborhoodSummary,
3192
3523
  getSearchUi,
3193
3524
  getSimilarListings,
3194
3525
  getSite,
@@ -3197,6 +3528,7 @@ function createGaragemClient(options = {}) {
3197
3528
  hrefForPathFilters,
3198
3529
  hrefWithExplicitPage,
3199
3530
  isListingDetailPath,
3531
+ isPhotoSearchOnPin,
3200
3532
  isStudioPreviewHost,
3201
3533
  isValidPhone,
3202
3534
  isVisitSlotAllowed,
@@ -3215,6 +3547,8 @@ function createGaragemClient(options = {}) {
3215
3547
  listingMediaOverlays,
3216
3548
  listingPublicPath,
3217
3549
  listingValues,
3550
+ marketExportsAvailableAt,
3551
+ marketPositionLabel,
3218
3552
  mergeAppliedSearchQueryIntoSearch,
3219
3553
  nationalPhoneDigits,
3220
3554
  normalizeVisitDate,
@@ -3230,15 +3564,20 @@ function createGaragemClient(options = {}) {
3230
3564
  pathFiltersToQueryFilters,
3231
3565
  pathLocationToFilterInput,
3232
3566
  phoneCountrySearchValue,
3567
+ photoSearchUrl,
3568
+ priceBandLabel,
3233
3569
  publicSearchHref,
3234
3570
  queryListings,
3235
3571
  rangeDraftFromPath,
3236
3572
  readPublicSearch,
3237
3573
  reduceAppliedSearchQuery,
3238
3574
  remaskPhoneForCountry,
3575
+ requestPriceEstimate,
3576
+ resolveMatchedCoverPhoto,
3239
3577
  resolvePublicSiteId,
3240
3578
  searchChromeModel,
3241
3579
  searchHrefUsesLegacyFilterQuery,
3580
+ searchListingPhotos,
3242
3581
  searchListings,
3243
3582
  searchResultsHeading,
3244
3583
  searchSortOptions,
@@ -3252,6 +3591,8 @@ function createGaragemClient(options = {}) {
3252
3591
  studioLeadInstruction,
3253
3592
  studioListingCardInstruction,
3254
3593
  studioListingDetailInstruction,
3594
+ studioMarketInstruction,
3595
+ studioPhotoSearchInstruction,
3255
3596
  studioSdkPinInstruction,
3256
3597
  studioSearchInstruction,
3257
3598
  studioSearchLandmarkInstruction,