@garagem-ai/site-sdk 0.13.6 → 0.14.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.mts +46 -24
- package/dist/index.d.ts +46 -24
- package/dist/index.js +72 -28
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +70 -28
- package/dist/index.mjs.map +1 -1
- package/dist/react.d.mts +1 -1
- package/dist/react.d.ts +1 -1
- package/dist/react.js +20 -2
- package/dist/react.js.map +1 -1
- package/dist/react.mjs +20 -2
- package/dist/react.mjs.map +1 -1
- package/dist/{types-photo-search-CVPyF9zC.d.mts → types-photo-search--3fBk3Cs.d.mts} +15 -3
- package/dist/{types-photo-search-CVPyF9zC.d.ts → types-photo-search--3fBk3Cs.d.ts} +15 -3
- package/package.json +1 -1
- package/src/analytics-document.ts +3 -3
- package/src/index.ts +2 -0
- package/src/listing-card-model.ts +28 -3
- package/src/search-engine.ts +2 -3
- package/src/studio-contract.ts +55 -23
- package/src/types.ts +8 -0
|
@@ -522,6 +522,14 @@ interface Listing {
|
|
|
522
522
|
} | null;
|
|
523
523
|
createdAt: string;
|
|
524
524
|
updatedAt: string;
|
|
525
|
+
/**
|
|
526
|
+
* Present when this card collapses several primary-market units of one
|
|
527
|
+
* building. `title` is the building name and `price` is the lowest
|
|
528
|
+
* public price in the result window.
|
|
529
|
+
*/
|
|
530
|
+
development?: {
|
|
531
|
+
unitCount: number;
|
|
532
|
+
} | null;
|
|
525
533
|
}
|
|
526
534
|
/**
|
|
527
535
|
* Full listing data including amenities, full media gallery, building
|
|
@@ -882,9 +890,8 @@ type LocationNameTables = {
|
|
|
882
890
|
* locations request failed: do not 404 the search. A path with no location
|
|
883
891
|
* (`/imoveis`, `/imoveis/venda`, `/imoveis/4-quartos`) is a normal search.
|
|
884
892
|
*
|
|
885
|
-
* Studio prompts
|
|
886
|
-
*
|
|
887
|
-
* export.
|
|
893
|
+
* Studio prompts call this helper. It has been on the npm tarball since
|
|
894
|
+
* 0.13.4, and the Studio pin (`minNpmVersion`) includes that release.
|
|
888
895
|
*/
|
|
889
896
|
declare function unknownSearchLocation(location: SearchPathFilters["location"] | null | undefined, tables: LocationNameTables | null | undefined): boolean;
|
|
890
897
|
declare function displayPathLocation(location: SearchPathFilters["location"], values?: LocationNameTables | null): SearchPathFilters["location"] | null;
|
|
@@ -964,6 +971,8 @@ type ListingCardModel = {
|
|
|
964
971
|
bathrooms: number | null;
|
|
965
972
|
parkingSpaces: number | null;
|
|
966
973
|
areaM2: number | null;
|
|
974
|
+
/** Units in a collapsed development card. Null for a single listing. */
|
|
975
|
+
unitCount: number | null;
|
|
967
976
|
};
|
|
968
977
|
declare function listingLocationLabel(location: {
|
|
969
978
|
neighborhood?: string | null;
|
|
@@ -984,6 +993,9 @@ declare function toListingCardModel(listing: Pick<Listing, "id" | "listingCode"
|
|
|
984
993
|
city?: string | null;
|
|
985
994
|
state?: string | null;
|
|
986
995
|
};
|
|
996
|
+
development?: {
|
|
997
|
+
unitCount?: number | null;
|
|
998
|
+
} | null;
|
|
987
999
|
}): ListingCardModel;
|
|
988
1000
|
|
|
989
1001
|
/**
|
|
@@ -522,6 +522,14 @@ interface Listing {
|
|
|
522
522
|
} | null;
|
|
523
523
|
createdAt: string;
|
|
524
524
|
updatedAt: string;
|
|
525
|
+
/**
|
|
526
|
+
* Present when this card collapses several primary-market units of one
|
|
527
|
+
* building. `title` is the building name and `price` is the lowest
|
|
528
|
+
* public price in the result window.
|
|
529
|
+
*/
|
|
530
|
+
development?: {
|
|
531
|
+
unitCount: number;
|
|
532
|
+
} | null;
|
|
525
533
|
}
|
|
526
534
|
/**
|
|
527
535
|
* Full listing data including amenities, full media gallery, building
|
|
@@ -882,9 +890,8 @@ type LocationNameTables = {
|
|
|
882
890
|
* locations request failed: do not 404 the search. A path with no location
|
|
883
891
|
* (`/imoveis`, `/imoveis/venda`, `/imoveis/4-quartos`) is a normal search.
|
|
884
892
|
*
|
|
885
|
-
* Studio prompts
|
|
886
|
-
*
|
|
887
|
-
* export.
|
|
893
|
+
* Studio prompts call this helper. It has been on the npm tarball since
|
|
894
|
+
* 0.13.4, and the Studio pin (`minNpmVersion`) includes that release.
|
|
888
895
|
*/
|
|
889
896
|
declare function unknownSearchLocation(location: SearchPathFilters["location"] | null | undefined, tables: LocationNameTables | null | undefined): boolean;
|
|
890
897
|
declare function displayPathLocation(location: SearchPathFilters["location"], values?: LocationNameTables | null): SearchPathFilters["location"] | null;
|
|
@@ -964,6 +971,8 @@ type ListingCardModel = {
|
|
|
964
971
|
bathrooms: number | null;
|
|
965
972
|
parkingSpaces: number | null;
|
|
966
973
|
areaM2: number | null;
|
|
974
|
+
/** Units in a collapsed development card. Null for a single listing. */
|
|
975
|
+
unitCount: number | null;
|
|
967
976
|
};
|
|
968
977
|
declare function listingLocationLabel(location: {
|
|
969
978
|
neighborhood?: string | null;
|
|
@@ -984,6 +993,9 @@ declare function toListingCardModel(listing: Pick<Listing, "id" | "listingCode"
|
|
|
984
993
|
city?: string | null;
|
|
985
994
|
state?: string | null;
|
|
986
995
|
};
|
|
996
|
+
development?: {
|
|
997
|
+
unitCount?: number | null;
|
|
998
|
+
} | null;
|
|
987
999
|
}): ListingCardModel;
|
|
988
1000
|
|
|
989
1001
|
/**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@garagem-ai/site-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.1",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Typed, runtime-agnostic SDK for building custom real estate sites against the Garagem platform. Drop into any Next.js (or other JS) project to fetch listings, sites and CMS data.",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* A visit is a location, a listing, or a static page. Filter paths and
|
|
3
3
|
* `page` greater than 1 are the crawl space Studio's catch-all answers.
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
4
|
+
* The pinned tarball exports `isAnalyticsDocumentUrl` (since 0.13.6), so
|
|
5
|
+
* Studio prompts may name it. `analyticsDocumentGuardSource()` is the same
|
|
6
|
+
* check pasted into the generated client, which does not import the helper.
|
|
7
7
|
*/
|
|
8
8
|
|
|
9
9
|
const FILTER_SEGMENT_SOURCE =
|
package/src/index.ts
CHANGED
|
@@ -296,6 +296,8 @@ export {
|
|
|
296
296
|
studioAmenityInstruction,
|
|
297
297
|
studioLeadInstruction,
|
|
298
298
|
studioListingCardInstruction,
|
|
299
|
+
studioDevelopmentCardInstruction,
|
|
300
|
+
developmentCardPublished,
|
|
299
301
|
studioListingDetailInstruction,
|
|
300
302
|
studioPhotoInstruction,
|
|
301
303
|
studioPhotoInstructionFor,
|
|
@@ -24,6 +24,8 @@ export type ListingCardModel = {
|
|
|
24
24
|
bathrooms: number | null;
|
|
25
25
|
parkingSpaces: number | null;
|
|
26
26
|
areaM2: number | null;
|
|
27
|
+
/** Units in a collapsed development card. Null for a single listing. */
|
|
28
|
+
unitCount: number | null;
|
|
27
29
|
};
|
|
28
30
|
|
|
29
31
|
export function listingLocationLabel(location: {
|
|
@@ -37,6 +39,17 @@ export function listingLocationLabel(location: {
|
|
|
37
39
|
.join(", ");
|
|
38
40
|
}
|
|
39
41
|
|
|
42
|
+
function cardPriceLabel(
|
|
43
|
+
isPrivate: boolean,
|
|
44
|
+
collapsed: boolean,
|
|
45
|
+
price: number | null | undefined,
|
|
46
|
+
formattedPrice: string
|
|
47
|
+
): string {
|
|
48
|
+
if (isPrivate) return "Sob consulta";
|
|
49
|
+
if (collapsed && price != null) return `A partir de ${formattedPrice}`;
|
|
50
|
+
return formattedPrice;
|
|
51
|
+
}
|
|
52
|
+
|
|
40
53
|
export function toListingCardModel(
|
|
41
54
|
listing: Pick<
|
|
42
55
|
Listing,
|
|
@@ -63,10 +76,18 @@ export function toListingCardModel(
|
|
|
63
76
|
city?: string | null;
|
|
64
77
|
state?: string | null;
|
|
65
78
|
};
|
|
79
|
+
development?: { unitCount?: number | null } | null;
|
|
66
80
|
}
|
|
67
81
|
): ListingCardModel {
|
|
68
82
|
const isPrivate = listing.priceVisibility === "private";
|
|
69
83
|
const area = listing.property?.usableArea ?? listing.property?.totalArea;
|
|
84
|
+
const unitCount = listing.development?.unitCount;
|
|
85
|
+
const collapsed = typeof unitCount === "number" && unitCount > 1;
|
|
86
|
+
const formattedPrice = formatListingPrice(
|
|
87
|
+
listing.price,
|
|
88
|
+
"pt-BR",
|
|
89
|
+
listing.currency ?? "BRL"
|
|
90
|
+
);
|
|
70
91
|
return {
|
|
71
92
|
href: listingPublicPath(listing),
|
|
72
93
|
title: listing.title,
|
|
@@ -74,9 +95,12 @@ export function toListingCardModel(
|
|
|
74
95
|
businessLabel: listingBusinessLabel(listing.businessType),
|
|
75
96
|
priceVisibility: listing.priceVisibility,
|
|
76
97
|
price: listing.price,
|
|
77
|
-
priceLabel:
|
|
78
|
-
|
|
79
|
-
|
|
98
|
+
priceLabel: cardPriceLabel(
|
|
99
|
+
isPrivate,
|
|
100
|
+
collapsed,
|
|
101
|
+
listing.price,
|
|
102
|
+
formattedPrice
|
|
103
|
+
),
|
|
80
104
|
pricePeriod:
|
|
81
105
|
listing.businessType === "rental" && !isPrivate && listing.price != null
|
|
82
106
|
? "/mês"
|
|
@@ -89,5 +113,6 @@ export function toListingCardModel(
|
|
|
89
113
|
bathrooms: listing.property?.bathrooms ?? null,
|
|
90
114
|
parkingSpaces: listing.property?.parkingSpaces ?? null,
|
|
91
115
|
areaM2: area ?? null,
|
|
116
|
+
unitCount: collapsed && typeof unitCount === "number" ? unitCount : null,
|
|
92
117
|
};
|
|
93
118
|
}
|
package/src/search-engine.ts
CHANGED
|
@@ -136,9 +136,8 @@ function locationTableHasSlug(
|
|
|
136
136
|
* locations request failed: do not 404 the search. A path with no location
|
|
137
137
|
* (`/imoveis`, `/imoveis/venda`, `/imoveis/4-quartos`) is a normal search.
|
|
138
138
|
*
|
|
139
|
-
* Studio prompts
|
|
140
|
-
*
|
|
141
|
-
* export.
|
|
139
|
+
* Studio prompts call this helper. It has been on the npm tarball since
|
|
140
|
+
* 0.13.4, and the Studio pin (`minNpmVersion`) includes that release.
|
|
142
141
|
*/
|
|
143
142
|
export function unknownSearchLocation(
|
|
144
143
|
location: SearchPathFilters["location"] | null | undefined,
|
package/src/studio-contract.ts
CHANGED
|
@@ -17,9 +17,11 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
17
17
|
/**
|
|
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
|
-
* this and move that
|
|
21
|
-
* `
|
|
22
|
-
* prompt-safe lists.
|
|
20
|
+
* this and move names that tarball newly exports out of
|
|
21
|
+
* `optionalReactExports` / `unpublishedSearchExports` /
|
|
22
|
+
* `unpublishedPhoneExports` into the prompt-safe lists. Names that stay
|
|
23
|
+
* forbidden after they ship (`searchChromeModel`, `rangeDraftFromPath`)
|
|
24
|
+
* do not move. Do not bump here until that tarball is on npm.
|
|
23
25
|
* Phone mask helpers shipped in 0.6.0. Map search
|
|
24
26
|
* (`useMapSearch`, `searchListingsInBounds`) shipped in 0.9.0 — 0.7.0
|
|
25
27
|
* does not export them. Property registration shipped in 0.10.0.
|
|
@@ -28,10 +30,12 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
28
30
|
* 0.12.0. Analytics catalog events (`trackListingView` plus the search
|
|
29
31
|
* and lead emitters) shipped in 0.13.0. `property_search` sends a city
|
|
30
32
|
* or neighborhood only when the site's location table knows it, as of
|
|
31
|
-
* 0.13.2.
|
|
32
|
-
*
|
|
33
|
+
* 0.13.2. Development cards (`model.unitCount`, "A partir de" on a
|
|
34
|
+
* public price) shipped in 0.14.0. Search filter helpers
|
|
35
|
+
* (`visibleSearchFilters` / `toolbarFilterIds`) shipped in 0.4.12 and
|
|
36
|
+
* remain on this pin.
|
|
33
37
|
*/
|
|
34
|
-
minNpmVersion: "0.
|
|
38
|
+
minNpmVersion: "0.14.0",
|
|
35
39
|
/** Historical: older tarballs inject card CSS when those components mount. */
|
|
36
40
|
selfInjectSince: "0.4.2",
|
|
37
41
|
chromeStrategy: "app-owned" as const,
|
|
@@ -133,8 +137,9 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
133
137
|
/**
|
|
134
138
|
* Names already on the pinned npm tarball (`minNpmVersion`) — safe for
|
|
135
139
|
* Studio prompts and completeness. Includes `visibleSearchFilters` +
|
|
136
|
-
* `toolbarFilterIds` (shipped in 0.4.12)
|
|
137
|
-
*
|
|
140
|
+
* `toolbarFilterIds` (shipped in 0.4.12) and `unknownSearchLocation`
|
|
141
|
+
* (shipped in 0.13.4). Do not confuse with `unpublishedSearchExports`
|
|
142
|
+
* (`searchChromeModel`, …).
|
|
138
143
|
*/
|
|
139
144
|
searchExports: [
|
|
140
145
|
"searchResultsHeading",
|
|
@@ -145,22 +150,18 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
145
150
|
"hrefWithExplicitPage",
|
|
146
151
|
"countOptionLabel",
|
|
147
152
|
"countFacetChoices",
|
|
153
|
+
"unknownSearchLocation",
|
|
148
154
|
] as const,
|
|
149
155
|
/**
|
|
150
|
-
*
|
|
151
|
-
* `
|
|
152
|
-
*
|
|
153
|
-
*
|
|
156
|
+
* Exported by the pinned tarball, and still forbidden in prompts.
|
|
157
|
+
* `searchChromeModel` is retired bundled chrome — the prompt names
|
|
158
|
+
* `visibleSearchFilters` and `toolbarFilterIds` instead. `rangeDraftFromPath`
|
|
159
|
+
* stays unnamed; price and area drafts stay local state. Helpers the pin
|
|
160
|
+
* allows (`unknownSearchLocation`, `isAnalyticsDocumentUrl`) are not here.
|
|
154
161
|
*/
|
|
155
162
|
unpublishedSearchExports: [
|
|
156
163
|
"searchChromeModel",
|
|
157
164
|
"rangeDraftFromPath",
|
|
158
|
-
// `unknownSearchLocation` is in git. Prompts inline the same check with
|
|
159
|
-
// `parseSearchPublicPath` + `locationsPath` until this name is on the pin.
|
|
160
|
-
"unknownSearchLocation",
|
|
161
|
-
// In git. The installed client inlines the check. Naming it in a prompt
|
|
162
|
-
// makes v0 import it from the pinned tarball, which does not export it.
|
|
163
|
-
"isAnalyticsDocumentUrl",
|
|
164
165
|
] as const,
|
|
165
166
|
/**
|
|
166
167
|
* maps.fndn.ai helpers (static map, street view, boundaries, travel
|
|
@@ -248,11 +249,21 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
248
249
|
/**
|
|
249
250
|
* Listing-view analytics. Search and lead catalog events need no prompt:
|
|
250
251
|
* `usePublicSearch` and the lead helpers emit them from `analyticsSince`.
|
|
251
|
-
*
|
|
252
|
-
*
|
|
252
|
+
* `isAnalyticsDocumentUrl` shipped in 0.13.6 and is prompt-safe on this
|
|
253
|
+
* pin (it is not a search import). Below `analyticsSince`,
|
|
254
|
+
* `studioListingViewInstruction` prints nothing and
|
|
255
|
+
* `studioCodegenContractViolations` flags these names.
|
|
253
256
|
*/
|
|
254
|
-
analyticsExports: ["trackListingView"] as const,
|
|
257
|
+
analyticsExports: ["trackListingView", "isAnalyticsDocumentUrl"] as const,
|
|
255
258
|
analyticsSince: "0.13.0",
|
|
259
|
+
/**
|
|
260
|
+
* Development cards (`model.unitCount`, "A partir de" on `priceLabel`).
|
|
261
|
+
* The search API can return `listing.development` before this pin.
|
|
262
|
+
* Prompts must not name `unitCount` until `minNpmVersion` reaches
|
|
263
|
+
* `developmentCardSince` — v0 copies the field and an older
|
|
264
|
+
* `toListingCardModel` does not set it.
|
|
265
|
+
*/
|
|
266
|
+
developmentCardSince: "0.14.0",
|
|
256
267
|
} as const;
|
|
257
268
|
|
|
258
269
|
export type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
|
|
@@ -449,9 +460,30 @@ export function studioLeadInstruction(): string {
|
|
|
449
460
|
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.`;
|
|
450
461
|
}
|
|
451
462
|
|
|
452
|
-
export function
|
|
463
|
+
export function developmentCardPublished(
|
|
464
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
465
|
+
): boolean {
|
|
466
|
+
return compareSemver(pin, STUDIO_SDK_CONTRACT.developmentCardSince) >= 0;
|
|
467
|
+
}
|
|
468
|
+
|
|
469
|
+
/**
|
|
470
|
+
* How a generated card renders a collapsed development. Empty until the
|
|
471
|
+
* pin ships `toListingCardModel`'s `unitCount`.
|
|
472
|
+
*/
|
|
473
|
+
export function studioDevelopmentCardInstruction(
|
|
474
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
475
|
+
): string {
|
|
476
|
+
if (!developmentCardPublished(pin)) return "";
|
|
477
|
+
return `Development cards: \`toListingCardModel\` sets \`model.unitCount\` when several primary-market units were collapsed into one card, and \`model.priceLabel\` already starts with "A partir de". When \`model.unitCount\` is greater than 1, show it as "N unidades" and omit that line when it is null. Keep \`model.title\`, \`model.priceLabel\`, and \`model.href\`. Do not group listings in the page.`;
|
|
478
|
+
}
|
|
479
|
+
|
|
480
|
+
export function studioListingCardInstruction(
|
|
481
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
482
|
+
): string {
|
|
453
483
|
const names = STUDIO_SDK_CONTRACT.listingCardExports.join(", ");
|
|
454
|
-
|
|
484
|
+
const base = `Listing card (site-wide). WRITE \`components/garagem/listing-card.tsx\` — one module for home, search results, and similar listings. Do not invent a second card. From \`${STUDIO_SDK_PACKAGE}\` import ${names}. \`const model = toListingCardModel(listing)\`. href is \`model.href\` / \`listingPublicPath(listing)\` — never \`listing.id\` or \`property.id\`. Skip the card or omit the link when href is empty (no \`href=""\`, no \`href="#"\`). Must show title (\`model.title\`) and price (\`model.priceLabel\` — “Sob consulta” when private; \`model.pricePeriod\` “/mês” when present, omit when null). Photo: \`model.coverSrc\` as img \`src\`, alt \`model.coverAlt\`; skip the img when cover is missing; an empty-photo block is allowed; never Unsplash, \`/placeholder.svg\`, or invented \`?query=\` images. Show when present, omit the line when missing: \`locationLabel\` (else \`propertyType\`), \`listingBusinessLabel\` / \`model.businessLabel\`, bedrooms, bathrooms, parkingSpaces, area via \`formatAreaM2\`. Never interpolate the listing object as a React child. Design is free (grid vs carousel vs mosaic; radius is site \`--radius\`). WRITE \`components/garagem/listing-card-skeleton.tsx\` only for a slot whose content is still unknown — never as a \`<Suspense>\` fallback that replaces the catalog, and never the text “Carregando imóveis…”. Do not \`if (search.loading) return\` that skeleton inside the search client.`;
|
|
485
|
+
const development = studioDevelopmentCardInstruction(pin);
|
|
486
|
+
return development ? `${base}\n\n${development}` : base;
|
|
455
487
|
}
|
|
456
488
|
|
|
457
489
|
export function studioListingDetailInstruction(): string {
|
package/src/types.ts
CHANGED
|
@@ -110,6 +110,14 @@ export interface Listing {
|
|
|
110
110
|
} | null;
|
|
111
111
|
createdAt: string;
|
|
112
112
|
updatedAt: string;
|
|
113
|
+
/**
|
|
114
|
+
* Present when this card collapses several primary-market units of one
|
|
115
|
+
* building. `title` is the building name and `price` is the lowest
|
|
116
|
+
* public price in the result window.
|
|
117
|
+
*/
|
|
118
|
+
development?: {
|
|
119
|
+
unitCount: number;
|
|
120
|
+
} | null;
|
|
113
121
|
}
|
|
114
122
|
|
|
115
123
|
/**
|