@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 +91 -0
- package/dist/index.d.mts +330 -166
- package/dist/index.d.ts +330 -166
- package/dist/index.js +365 -24
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +350 -24
- package/dist/index.mjs.map +1 -1
- package/dist/react.d.mts +41 -2
- package/dist/react.d.ts +41 -2
- package/dist/react.js +194 -0
- package/dist/react.js.map +1 -1
- package/dist/react.mjs +192 -0
- package/dist/react.mjs.map +1 -1
- package/dist/{search-engine-CtnLzmwW.d.mts → types-photo-search-OeONNDxl.d.mts} +204 -1
- package/dist/{search-engine-CtnLzmwW.d.ts → types-photo-search-OeONNDxl.d.ts} +204 -1
- package/package.json +2 -1
- package/src/fetchers-market.ts +216 -0
- package/src/fetchers-photo-search.ts +101 -0
- package/src/index.ts +61 -0
- package/src/market-labels.ts +51 -0
- package/src/photo-search-cover.ts +90 -0
- package/src/react/index.ts +8 -0
- package/src/react/use-public-photo-search.ts +165 -0
- package/src/studio-contract.ts +125 -23
- package/src/types-market.ts +138 -0
- package/src/types-photo-search.ts +55 -0
- package/src/types.ts +7 -0
package/src/studio-contract.ts
CHANGED
|
@@ -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
|
|
22
|
-
* until that tarball is on npm.
|
|
23
|
-
*
|
|
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.
|
|
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: {
|
|
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
|
|
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: [
|
|
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`
|
|
102
|
-
*
|
|
103
|
-
* `
|
|
104
|
-
*
|
|
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 =
|
|
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
|
-
|
|
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.
|
|
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;
|