@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.
@@ -18,11 +18,13 @@ export const STUDIO_SDK_CONTRACT = {
18
18
  * Exact pin for generated Studio sites. Must match a tarball already on
19
19
  * npm — v0 installs this version. After a later changeset publishes, bump
20
20
  * this and move that release's names from `optionalReactExports` /
21
- * `unpublishedSearchExports` into the prompt-safe lists. Do not bump here
22
- * until that tarball is on npm. Headless SearchPage already shipped in
23
- * 0.4.12 (`visibleSearchFilters` / `toolbarFilterIds` are on that pin).
21
+ * `unpublishedSearchExports` / `unpublishedPhoneExports` into the
22
+ * prompt-safe lists. Do not bump here until that tarball is on npm.
23
+ * Phone mask helpers shipped in 0.6.0. Search filter helpers
24
+ * (`visibleSearchFilters` / `toolbarFilterIds`) shipped in 0.4.12 and
25
+ * remain on this pin.
24
26
  */
25
- minNpmVersion: "0.4.12",
27
+ minNpmVersion: "0.6.0",
26
28
  /** Historical: older tarballs inject card CSS when those components mount. */
27
29
  selfInjectSince: "0.4.2",
28
30
  chromeStrategy: "app-owned" as const,
@@ -34,7 +36,9 @@ export const STUDIO_SDK_CONTRACT = {
34
36
  * “never import”) — v0 copies the identifier and the preview ESM loader
35
37
  * throws FatalRendererError.
36
38
  */
37
- optionalReactExports: {} as Record<string, string>,
39
+ optionalReactExports: {
40
+ usePublicPhotoSearch: "0.7.0",
41
+ } as Record<string, string>,
38
42
  /**
39
43
  * Former `/react` chrome (including card/skeleton inject). Completeness
40
44
  * flags imports as mismatch (not in `reactExports`). Prompts must not
@@ -75,18 +79,9 @@ export const STUDIO_SDK_CONTRACT = {
75
79
  "formatListingPrice",
76
80
  ] as const,
77
81
  /**
78
- * Prompt-safe phone helpers on `minNpmVersion`. Empty until a published
79
- * tarball exports them and this pin bumps — then move names here from
80
- * `unpublishedPhoneExports`.
82
+ * Prompt-safe phone helpers on `minNpmVersion` (published in 0.6.0).
81
83
  */
82
- phoneExports: [] as const,
83
- /**
84
- * Headless phone mask helpers in git / newer tarballs but not on
85
- * `minNpmVersion` (0.4.12). Prompts, completeness, and repair text must
86
- * not mention these until the pin bumps — v0 installs the pin and the
87
- * ESM loader throws on missing named exports.
88
- */
89
- unpublishedPhoneExports: [
84
+ phoneExports: [
90
85
  "PHONE_COUNTRIES",
91
86
  "formatPhoneNational",
92
87
  "toE164",
@@ -96,12 +91,19 @@ export const STUDIO_SDK_CONTRACT = {
96
91
  "findPhoneCountry",
97
92
  "remaskPhoneForCountry",
98
93
  ] as const,
94
+ /**
95
+ * Headless phone helpers in git but not on `minNpmVersion`. Prompts,
96
+ * completeness, and repair text must not mention these until the pin
97
+ * bumps — v0 installs the pin and the ESM loader throws on missing
98
+ * named exports.
99
+ */
100
+ unpublishedPhoneExports: [] as const,
99
101
  amenityExports: ["listingAmenityGroups"] as const,
100
102
  /**
101
- * Names already on the pinned npm tarball (`minNpmVersion` / 0.4.12) —
102
- * safe for Studio prompts and completeness. Includes
103
- * `visibleSearchFilters` + `toolbarFilterIds` (shipped in 0.4.12). Do not
104
- * confuse with `unpublishedSearchExports` (`searchChromeModel`, …).
103
+ * Names already on the pinned npm tarball (`minNpmVersion`) — safe for
104
+ * Studio prompts and completeness. Includes `visibleSearchFilters` +
105
+ * `toolbarFilterIds` (shipped in 0.4.12). Do not confuse with
106
+ * `unpublishedSearchExports` (`searchChromeModel`, …).
105
107
  */
106
108
  searchExports: [
107
109
  "searchResultsHeading",
@@ -121,10 +123,49 @@ export const STUDIO_SDK_CONTRACT = {
121
123
  "searchChromeModel",
122
124
  "rangeDraftFromPath",
123
125
  ] as const,
126
+ /**
127
+ * Market-data helpers (neighborhood price summary, listing market
128
+ * position, visitor price estimate, pt-BR labels). They ship in
129
+ * `marketExportsSince` and are prompt-safe only once `minNpmVersion`
130
+ * reaches that release; below it `studioCodegenContractViolations` flags
131
+ * the names and `studioMarketInstruction()` tells Studio not to generate
132
+ * the blocks at all. Every helper answers `available: false` unless the
133
+ * site's organization holds the IPTU module (`iptu_itbi_integration`)
134
+ * and the city is covered — generated sites render these blocks
135
+ * conditionally and never show cadastral or transaction data.
136
+ */
137
+ marketExports: [
138
+ "getNeighborhoodSummary",
139
+ "getListingMarketPosition",
140
+ "requestPriceEstimate",
141
+ "marketPositionLabel",
142
+ "priceBandLabel",
143
+ ] as const,
144
+ marketExportsSince: "0.7.0",
145
+ /**
146
+ * Photo search ("busca pelo que as fotos mostram"): main-package helpers
147
+ * that ship together with the `/react` hook listed in
148
+ * `optionalReactExports` (`usePublicPhotoSearch`). Prompt-safe only once
149
+ * `minNpmVersion` reaches `photoSearchSince` — `studioPhotoSearchInstruction`
150
+ * and the Studio guidance print nothing before that, and
151
+ * `studioCodegenContractViolations` flags the names until then.
152
+ */
153
+ photoSearchExports: [
154
+ "searchListingPhotos",
155
+ "applyMatchedPhotoCover",
156
+ ] as const,
157
+ photoSearchSince: "0.7.0",
124
158
  } as const;
125
159
 
126
160
  export type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
127
161
 
162
+ /** Whether the pinned tarball carries the photo-search surface. */
163
+ export function isPhotoSearchOnPin(
164
+ pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
165
+ ): boolean {
166
+ return compareSemver(pin, STUDIO_SDK_CONTRACT.photoSearchSince) >= 0;
167
+ }
168
+
128
169
  /**
129
170
  * Global Studio content width. Mirrors Editor default `7xl` / `px-4`
130
171
  * without the Marca picker — v0 sites are not `@garagem/ui`.
@@ -231,13 +272,14 @@ export function unavailableReactImports(source: string, pin: string): string[] {
231
272
 
232
273
  export function studioSdkPinInstruction(): string {
233
274
  const version = STUDIO_SDK_CONTRACT.minNpmVersion;
234
- const names = STUDIO_SDK_CONTRACT.reactExports.join(", ");
275
+ const names = [...reactExportsAvailableAt(version)].join(", ");
235
276
  return `In \`package.json\` set \`"@garagem-ai/site-sdk": "${version}"\` (exact). Import only these \`${STUDIO_SDK_PACKAGE}/react\` names: ${names}.`;
236
277
  }
237
278
 
238
279
  export function studioLeadInstruction(): string {
239
280
  const names = STUDIO_SDK_CONTRACT.leadExports.join(", ");
240
- return `Listing-detail visit/contact leads: import ${names} from \`${STUDIO_SDK_PACKAGE}\` (the main package, not \`/react\`). Call \`submitVisitLead\` / \`submitContactLead\` — 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 — do not invent a second mask and do not import \`@garagem/ui\` PhoneInput.`;
281
+ const phone = STUDIO_SDK_CONTRACT.phoneExports.join(", ");
282
+ return `Listing-detail visit/contact leads: import ${names} from \`${STUDIO_SDK_PACKAGE}\` (the main package, not \`/react\`). Call \`submitVisitLead\` / \`submitContactLead\` — 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.`;
241
283
  }
242
284
 
243
285
  export function studioListingCardInstruction(): string {
@@ -260,6 +302,46 @@ export function studioSearchInstruction(): string {
260
302
  return `Search: import ${reactNames} from \`${STUDIO_SDK_PACKAGE}/react\`. From \`${STUDIO_SDK_PACKAGE}\` import ${libNames}. Prefetch \`getSearchUi\` + \`queryListings\` on the server page. \`const search = usePublicSearch({ siteId, baseUrl: GARAGEM_API_BASE, search: searchFromServer, initial })\` where \`searchFromServer\` is \`new URLSearchParams(await searchParams).toString()\` — never shorthand \`{ search }\` beside \`const search =\` (temporal dead zone). Do not wrap this UI in \`<Suspense>\` and do not add a route \`loading\` file — heading and cards are ordinary elements in the document, visible with JavaScript off. Compose the page UI in the app — do not paste a canonical search TSX. Required chrome (design is free; omit none): query (\`qDraft\` / \`setQDraft\` / form \`preventDefault\` + \`submitQuery\`), heading (count span FIRST then h1 from \`searchResultsHeading(search.pathFilters, search.schema?.dictionary, search.locationNames)\` — never \`searchResultsHeading({})\`), toolbar (\`toolbarFilterIds\` + \`applyFilter\`; range “Atualizar” on that toolbar item only) vs sheet (\`visibleSearchFilters\` extras, \`stageFilter\`, one footer \`applyStaged\`), sort (\`searchSortOptions\` + \`setSort\`; first option id is \`""\` / “Mais relevantes” — map **only** that empty id to Select sentinel \`"relevancia"\` (\`opt.id || "relevancia"\`), never \`SelectItem value=""\` and never give “Mais recentes” (\`id: "recentes"\`, \`?ordenar=recentes\`) that sentinel; on change \`setSort(id === "relevancia" ? "" : id)\` so recentes stays recentes. Closed trigger shows the option \`.label\`, never \`{search.applied.sort}\`), grid (\`listings.map\` + the site listing-card module; listing-card-skeleton only for a slot whose content is still unknown, never as a Suspense fallback; do not \`throw\` in that chrome), pagination (\`paginationPages\` + \`hrefWithExplicitPage\`). Never interpolate \`schema\`, \`pathFilters\`, or a filter object as a React child. \`queryListings\` key is \`params\`. The URL is the document. Count text is \`{search.total}\` only. Heading is one row; font size lives on the container and the span and h1 use \`font-size: inherit\`. Sort trigger shows the option label (“Mais relevantes” when \`ordenar\` is absent), chevron at the end, same height as the toolbar controls. Toolbar ranges open a Popover form (not DropdownMenu — Menu typeahead swallows digit keys) whose submit calls \`applyFilter\`; the popup clips and the two inputs stay inside (\`min-w-0\`, no \`w-64\`). Reset min/max drafts when the popover opens and when the applied path range changes. The sheet omits toolbar ids (price, bedrooms) so Preço is never a heading without inputs. Sheet DialogContent uses \`h-[min(640px,85dvh)]\` (not max-h alone) so the body ScrollArea can move. Tipo de imóvel, características and comodidades each use a nested ScrollArea with \`h-56 overflow-hidden\` (viewport \`h-full\`). Area is two inputs in schema order with no “Aplicar”; the footer stages then applyStaged. Never read \`staged[filter.id]\` — path keys are \`bedrooms\` / \`listingType\` / \`bathrooms\`. Bedrooms Select reads \`pathFilters.bedrooms\` so \`/imoveis/4-quartos\` checks \`"4"\` and shows the same trigger dot as price. Bathrooms and parking pressed state uses \`pathFilterHasOption\`. Limpar keeps location plus toolbar price and bedrooms via \`clearStagedPathFilters\` and \`toolbarFilterIds\`; do not call \`clearStaged\` for that button. It enables only when staged has a path filter other than location and those kept toolbar ids. Each multi-select \`stageFilter\` value is one option id, never a concatenated slug; \`checked\` uses \`pathFilterHasOption\`. Listing type does not pass the clicked id: no path value shows every checkbox checked, unchecking one stages the other option's id, and the last box stays checked. Price inputs use formatGroupedInteger. The closed price and bedrooms triggers keep the filter label plus a dot when set — never the literal range. Empty price calls applyFilter(id, undefined); never send 0 or 1000000000. Area is a plain integer (not that mask). The results button stageFilter property_area_total with both drafts, then applyStaged. Never send 0 or 100000. Count buttons pass the option id (\`"2"\`), never the label \`"2+"\`. Property type, features, and amenities render in pt-BR label order. Do not set \`[data-slot="search-sort"] { flex-direction: column }\` in a \`<style>\` tag; that selector is row so the chevron sits beside the label. Empty copy: ${JSON.stringify(SEARCH_EMPTY_COPY)}`;
261
303
  }
262
304
 
305
+ /** True when the pinned tarball ships the market-data helpers. */
306
+ export function marketExportsAvailableAt(pin: string): boolean {
307
+ return compareSemver(pin, STUDIO_SDK_CONTRACT.marketExportsSince) >= 0;
308
+ }
309
+
310
+ /**
311
+ * Market-data blocks (neighborhood price summary, listing market position,
312
+ * visitor price estimate). Names appear only when the pin ships them; below
313
+ * that pin the instruction carries no identifiers (v0 copies any it sees).
314
+ */
315
+ export function studioMarketInstruction(
316
+ pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
317
+ ): string {
318
+ if (!marketExportsAvailableAt(pin)) {
319
+ 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 — 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.`;
320
+ }
321
+ const [summary, position, estimate, positionLabel, bandLabel] =
322
+ STUDIO_SDK_CONTRACT.marketExports;
323
+ const names = STUDIO_SDK_CONTRACT.marketExports.join(", ");
324
+ 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 — 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 “dados indisponíveis”, never a local fallback number. The payloads carry only aggregates and a trimmed estimate — 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\`, …) — do not print them. Three blocks (all optional, design is free):
325
+ - 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²\`) and \`summary.sampleSize\` (“com base em N vendas”); omit the sample line when null.
326
+ - 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)\` (“8% abaixo da mediana do bairro”) and \`${bandLabel}(position)\` (“Na faixa do bairro, abaixo da mediana”); both return \`null\` when unavailable — 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.
327
+ - Visitor price estimate (\`/anunciar\` or a dedicated page, client component): a form with city, bairro, área (m²), 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\` – \`estimate.rangeHighFormatted\` and \`estimate.confidenceLabel\` mapped to pt-BR (alta / média / baixa). When \`available\` is false show \`estimate.message\` (pt-BR, already written) and the contact CTA. It is rate limited per visitor — disable the submit while pending. Never call it on page load.
328
+ 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.`;
329
+ }
330
+
331
+ /**
332
+ * Photo search ("busca pelo que as fotos mostram") codegen instruction.
333
+ * Empty until the pinned tarball ships the surface (`photoSearchSince`), so
334
+ * no prompt names an identifier v0 cannot import.
335
+ */
336
+ export function studioPhotoSearchInstruction(
337
+ pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
338
+ ): string {
339
+ if (!isPhotoSearchOnPin(pin)) return "";
340
+ const hook = "usePublicPhotoSearch";
341
+ const [fetcher, cover] = STUDIO_SDK_CONTRACT.photoSearchExports;
342
+ 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 — 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.`;
343
+ }
344
+
263
345
  export function studioChromeInstruction(): string {
264
346
  return `Card, skeleton, and search chrome markup are app-owned. Never \`import "${STUDIO_SDK_CONTRACT.forbiddenImports[0]}"\` — v0 preview cannot load npm CSS. Do not mount an SDK stylesheet. Theme with site tokens and \`--radius\` in \`app/globals.css\`.`;
265
347
  }
@@ -274,7 +356,13 @@ function mentionsExportName(text: string, name: string): boolean {
274
356
  */
275
357
  export function studioCodegenContractViolations(text: string): string[] {
276
358
  const violations: string[] = [];
277
- for (const name of Object.keys(STUDIO_SDK_CONTRACT.optionalReactExports)) {
359
+ for (const [name, since] of Object.entries(
360
+ STUDIO_SDK_CONTRACT.optionalReactExports
361
+ )) {
362
+ // Prompt-safe once the pinned tarball carries the name (same rule as
363
+ // `reactExportsAvailableAt`); before that v0 would copy an import the
364
+ // preview ESM loader cannot resolve.
365
+ if (compareSemver(STUDIO_SDK_CONTRACT.minNpmVersion, since) >= 0) continue;
278
366
  if (mentionsExportName(text, name)) violations.push(name);
279
367
  }
280
368
  for (const name of STUDIO_SDK_CONTRACT.retiredReactExports) {
@@ -292,7 +380,21 @@ export function studioCodegenContractViolations(text: string): string[] {
292
380
  violations.push(name);
293
381
  }
294
382
  }
383
+ if (!isPhotoSearchOnPin()) {
384
+ for (const name of STUDIO_SDK_CONTRACT.photoSearchExports) {
385
+ if (mentionsExportName(text, name) && !violations.includes(name)) {
386
+ violations.push(name);
387
+ }
388
+ }
389
+ }
295
390
  const pin = STUDIO_SDK_CONTRACT.minNpmVersion;
391
+ if (!marketExportsAvailableAt(pin)) {
392
+ for (const name of STUDIO_SDK_CONTRACT.marketExports) {
393
+ if (mentionsExportName(text, name) && !violations.includes(name)) {
394
+ violations.push(name);
395
+ }
396
+ }
397
+ }
296
398
  const available = reactExportsAvailableAt(pin);
297
399
  for (const name of parseReactSdkNamedImports(text)) {
298
400
  if (!available.has(name) && !violations.includes(name)) {
@@ -0,0 +1,138 @@
1
+ /**
2
+ * Market-data types for the public site.
3
+ *
4
+ * IPTU-module requirement: every market endpoint answers
5
+ * `{ available: false, reason }` (HTTP 200) unless the site's organization
6
+ * holds the IPTU module (`iptu_itbi_integration`), the city is covered and
7
+ * the integration is configured. Render these blocks conditionally on
8
+ * `available`. The payloads carry only aggregates and the trimmed estimate —
9
+ * never comparables, transactions or cadastral identifiers.
10
+ */
11
+
12
+ /** Why a market helper answered `available: false`. */
13
+ export type MarketUnavailableReason =
14
+ /** The organization does not hold the IPTU module (`iptu_itbi_integration`). */
15
+ | "module_not_enabled"
16
+ /** Market-data integration is not configured for this environment. */
17
+ | "not_configured"
18
+ /** The site id does not resolve to an active site. */
19
+ | "site_not_found"
20
+ /** The city is outside the covered-city matrix. */
21
+ | "city_unsupported"
22
+ /** Only sale prices are covered. */
23
+ | "listing_type_unsupported"
24
+ /** Listing price is private or missing. */
25
+ | "price_unavailable"
26
+ /** No usable aggregate for the request. */
27
+ | "no_data"
28
+ /** The SDK was rate limited (HTTP 429); try again later. */
29
+ | "rate_limited";
30
+
31
+ export type MarketPropertyType = "apartment" | "house";
32
+ export type MarketListingType = "sale" | "rent";
33
+
34
+ export interface NeighborhoodSummaryQuery {
35
+ /** City name or code (`"São Paulo"`, `"sp"`). */
36
+ city: string;
37
+ neighborhood: string;
38
+ /** Echoed back; the aggregate covers every property kind today. */
39
+ propertyType?: MarketPropertyType;
40
+ /** Defaults to `"sale"`; `"rent"` answers `listing_type_unsupported`. */
41
+ type?: MarketListingType;
42
+ }
43
+
44
+ export interface NeighborhoodSummary {
45
+ available: boolean;
46
+ reason: MarketUnavailableReason | null;
47
+ /** Normalized city code (`sp` / `rj` / `bh`) when supported. */
48
+ city: string;
49
+ neighborhood: string;
50
+ propertyType: MarketPropertyType | null;
51
+ type: MarketListingType;
52
+ /** Lookback window in months. */
53
+ months: number;
54
+ /** Centavos per m². */
55
+ pricePerSqmCents: {
56
+ p25: number | null;
57
+ p50: number | null;
58
+ p75: number | null;
59
+ };
60
+ /** Pre-formatted `R$ X/m²` strings (`"—"` when missing). */
61
+ pricePerSqmFormatted: {
62
+ p25: string;
63
+ p50: string;
64
+ p75: string;
65
+ };
66
+ sampleSize: number | null;
67
+ /** pt-BR copy when unavailable. */
68
+ message: string | null;
69
+ }
70
+
71
+ /**
72
+ * Where a listing sits against the neighborhood quartiles:
73
+ * - `below_range`: under P25
74
+ * - `lower_range`: P25 ≤ price/m² < P50
75
+ * - `upper_range`: P50 ≤ price/m² ≤ P75
76
+ * - `above_range`: over P75
77
+ */
78
+ export type MarketPriceBand =
79
+ | "below_range"
80
+ | "lower_range"
81
+ | "upper_range"
82
+ | "above_range";
83
+
84
+ export interface ListingMarketPosition {
85
+ available: boolean;
86
+ reason: MarketUnavailableReason | null;
87
+ listingId: string;
88
+ city: string | null;
89
+ neighborhood: string | null;
90
+ months: number;
91
+ /** Listing asking price per m², centavos. */
92
+ listingPricePerSqmCents: number | null;
93
+ listingPricePerSqmFormatted: string;
94
+ /** Neighborhood median (P50) price per m², centavos. */
95
+ medianPricePerSqmCents: number | null;
96
+ medianPricePerSqmFormatted: string;
97
+ /** Rounded percent vs the median; negative = below the median. */
98
+ percentVsMedian: number | null;
99
+ band: MarketPriceBand | null;
100
+ sampleSize: number | null;
101
+ message: string | null;
102
+ }
103
+
104
+ export interface PriceEstimateInput {
105
+ /** City name or code (`"São Paulo"`, `"sp"`). */
106
+ city: string;
107
+ neighborhood?: string;
108
+ street?: string;
109
+ streetNumber?: string;
110
+ /** 8 digits, no dash. */
111
+ postalCode?: string;
112
+ /** m², 10–10000. */
113
+ areaSqm: number;
114
+ bedrooms?: number;
115
+ bathrooms?: number;
116
+ parkingSpots?: number;
117
+ propertyType?: MarketPropertyType;
118
+ listingType?: MarketListingType;
119
+ }
120
+
121
+ export type PriceEstimateConfidence = "high" | "medium" | "low";
122
+
123
+ export interface PriceEstimate {
124
+ available: boolean;
125
+ reason: MarketUnavailableReason | null;
126
+ city: string;
127
+ neighborhood: string | null;
128
+ estimatedPriceCents: number | null;
129
+ estimatedPriceFormatted: string;
130
+ rangeLowCents: number | null;
131
+ rangeHighCents: number | null;
132
+ rangeLowFormatted: string;
133
+ rangeHighFormatted: string;
134
+ confidenceLabel: PriceEstimateConfidence | null;
135
+ sampleSize: number | null;
136
+ /** pt-BR copy when unavailable. */
137
+ message: string | null;
138
+ }
@@ -0,0 +1,55 @@
1
+ import type { Listing } from "./types";
2
+
3
+ /**
4
+ * "Busca pelo que as fotos mostram": search a site's catalog by what the
5
+ * public photos show (`GET /api/sites/{siteId}/search/photos`).
6
+ */
7
+ export interface PhotoSearchParams {
8
+ /** Free text describing the photo ("varanda gourmet com churrasqueira"). */
9
+ q: string;
10
+ /** Listings per page (API default 12, cap 24). */
11
+ limit?: number;
12
+ /** 1-based page inside the API's candidate window. */
13
+ page?: number;
14
+ }
15
+
16
+ /** The photo that matched the words, chosen the same way as the CRM cover switch. */
17
+ export interface MatchedListingPhoto {
18
+ /** Media id; stable across listings that share the same photo. */
19
+ id: string;
20
+ src: string;
21
+ alt: string;
22
+ caption: string | null;
23
+ /**
24
+ * Vector distance for a visual match (lower is closer). `null` when the
25
+ * photo matched through its caption / room type instead (an exact text
26
+ * match, accepted as-is by {@link applyMatchedPhotoCover}).
27
+ */
28
+ distance: number | null;
29
+ }
30
+
31
+ export interface PhotoSearchItem {
32
+ /** Same card shape as `getListings` / `queryListings`. */
33
+ listing: Listing;
34
+ matchedPhoto: MatchedListingPhoto;
35
+ /** Lane score; higher is closer. Items arrive nearest-first. */
36
+ score: number;
37
+ }
38
+
39
+ export interface PhotoSearchResult {
40
+ /**
41
+ * `false` when the tenant has not enabled photo search: `items` is empty
42
+ * and the site should hide the feature rather than show "no results".
43
+ */
44
+ available: boolean;
45
+ items: PhotoSearchItem[];
46
+ /** Matching listings across every page (bounded by the API candidate window). */
47
+ total: number;
48
+ page: number;
49
+ limit: number;
50
+ }
51
+
52
+ /** A listing card whose cover was swapped for the photo that matched the search. */
53
+ export type ListingWithMatchedPhoto = Listing & {
54
+ matchedPhoto: MatchedListingPhoto | null;
55
+ };
package/src/types.ts CHANGED
@@ -284,6 +284,13 @@ export interface QueryListingsResult {
284
284
  * This is the SDK's escape hatch when `queryListings` isn't expressive
285
285
  * enough (faceted search, multi-field sort, custom grouping). It's an
286
286
  * open dictionary on purpose; the only required field is `q`.
287
+ *
288
+ * The endpoint only forwards allowlisted query / filter / sort / pagination /
289
+ * facet / grouping / highlight params. Anything that would make Typesense
290
+ * call out (`vector_query`, `nl_query`, `conversation*`, `preset`,
291
+ * `remote_embedding_*`), curation overrides (`pinned_hits`, `hidden_hits`),
292
+ * `collection`, and embedding fields in `query_by` / `include_fields` are
293
+ * dropped server-side; `per_page` is capped at 250.
287
294
  */
288
295
  export interface SearchListingsParams {
289
296
  q: string;