@garagem-ai/site-sdk 0.13.5 → 0.14.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.d.mts +31 -12
- package/dist/index.d.ts +31 -12
- package/dist/index.js +132 -6
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +128 -6
- 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 +66 -2
- package/dist/react.js.map +1 -1
- package/dist/react.mjs +66 -2
- package/dist/react.mjs.map +1 -1
- package/dist/{types-photo-search-CVPyF9zC.d.mts → types-photo-search-CokmqLjn.d.mts} +13 -0
- package/dist/{types-photo-search-CVPyF9zC.d.ts → types-photo-search-CokmqLjn.d.ts} +13 -0
- package/package.json +1 -1
- package/src/analytics-document.ts +90 -0
- package/src/analytics.ts +13 -0
- package/src/index.ts +6 -0
- package/src/listing-card-model.ts +28 -3
- package/src/studio-contract.ts +34 -2
- 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
|
|
@@ -964,6 +972,8 @@ type ListingCardModel = {
|
|
|
964
972
|
bathrooms: number | null;
|
|
965
973
|
parkingSpaces: number | null;
|
|
966
974
|
areaM2: number | null;
|
|
975
|
+
/** Units in a collapsed development card. Null for a single listing. */
|
|
976
|
+
unitCount: number | null;
|
|
967
977
|
};
|
|
968
978
|
declare function listingLocationLabel(location: {
|
|
969
979
|
neighborhood?: string | null;
|
|
@@ -984,6 +994,9 @@ declare function toListingCardModel(listing: Pick<Listing, "id" | "listingCode"
|
|
|
984
994
|
city?: string | null;
|
|
985
995
|
state?: string | null;
|
|
986
996
|
};
|
|
997
|
+
development?: {
|
|
998
|
+
unitCount?: number | null;
|
|
999
|
+
} | null;
|
|
987
1000
|
}): ListingCardModel;
|
|
988
1001
|
|
|
989
1002
|
/**
|
|
@@ -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
|
|
@@ -964,6 +972,8 @@ type ListingCardModel = {
|
|
|
964
972
|
bathrooms: number | null;
|
|
965
973
|
parkingSpaces: number | null;
|
|
966
974
|
areaM2: number | null;
|
|
975
|
+
/** Units in a collapsed development card. Null for a single listing. */
|
|
976
|
+
unitCount: number | null;
|
|
967
977
|
};
|
|
968
978
|
declare function listingLocationLabel(location: {
|
|
969
979
|
neighborhood?: string | null;
|
|
@@ -984,6 +994,9 @@ declare function toListingCardModel(listing: Pick<Listing, "id" | "listingCode"
|
|
|
984
994
|
city?: string | null;
|
|
985
995
|
state?: string | null;
|
|
986
996
|
};
|
|
997
|
+
development?: {
|
|
998
|
+
unitCount?: number | null;
|
|
999
|
+
} | null;
|
|
987
1000
|
}): ListingCardModel;
|
|
988
1001
|
|
|
989
1002
|
/**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@garagem-ai/site-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
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",
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A visit is a location, a listing, or a static page. Filter paths and
|
|
3
|
+
* `page` greater than 1 are the crawl space Studio's catch-all answers.
|
|
4
|
+
* `analyticsDocumentGuardSource()` is the same check pasted into the
|
|
5
|
+
* generated client, which cannot import this helper from the pinned tarball.
|
|
6
|
+
* Prompts must not name `isAnalyticsDocumentUrl`.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
const FILTER_SEGMENT_SOURCE =
|
|
10
|
+
"(?:^|-)(?:quartos|banheiros|suites|suite|vagas)$|(?:^|-)(?:reais|m2)$|^mapa$";
|
|
11
|
+
|
|
12
|
+
const CLICK_ID_SOURCE =
|
|
13
|
+
"^(?:fbclid|gclid|gbraid|wbraid|msclkid|ttclid|igshid|yclid|twclid|mc_eid|mc_cid|gad_source|_gl)$";
|
|
14
|
+
|
|
15
|
+
const DOCUMENT_QUERY_KEYS = ["q", "ordenar", "page", "pagina"] as const;
|
|
16
|
+
|
|
17
|
+
const FILTER_SEGMENT = new RegExp(FILTER_SEGMENT_SOURCE, "i");
|
|
18
|
+
const CLICK_ID = new RegExp(CLICK_ID_SOURCE);
|
|
19
|
+
|
|
20
|
+
/** `true` when this URL is a page a person opened, not a crawl of filters. */
|
|
21
|
+
export function isAnalyticsDocumentUrl(href: string): boolean {
|
|
22
|
+
let url: URL;
|
|
23
|
+
try {
|
|
24
|
+
url = new URL(href, "https://site.invalid");
|
|
25
|
+
} catch {
|
|
26
|
+
return true;
|
|
27
|
+
}
|
|
28
|
+
const pageRaw = param(url, "page") ?? param(url, "pagina");
|
|
29
|
+
if (pageRaw != null && pageRaw !== "") {
|
|
30
|
+
const page = Number(pageRaw);
|
|
31
|
+
if (!Number.isInteger(page) || page !== 1) return false;
|
|
32
|
+
}
|
|
33
|
+
const path = url.pathname.replace(/\/+$/, "").toLowerCase() || "/";
|
|
34
|
+
if (path !== "/imoveis" && !path.startsWith("/imoveis/")) return true;
|
|
35
|
+
for (const key of url.searchParams.keys()) {
|
|
36
|
+
if (ignoredQuery(key.toLowerCase())) continue;
|
|
37
|
+
return false;
|
|
38
|
+
}
|
|
39
|
+
const segments = path.split("/").filter(Boolean).slice(1);
|
|
40
|
+
return segments.every((segment) => !FILTER_SEGMENT.test(segment));
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
function param(url: URL, name: string): string | null {
|
|
44
|
+
for (const [key, value] of url.searchParams) {
|
|
45
|
+
if (key.toLowerCase() === name) return value;
|
|
46
|
+
}
|
|
47
|
+
return null;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function ignoredQuery(key: string): boolean {
|
|
51
|
+
return (
|
|
52
|
+
(DOCUMENT_QUERY_KEYS as readonly string[]).includes(key) ||
|
|
53
|
+
key.startsWith("utm_") ||
|
|
54
|
+
CLICK_ID.test(key)
|
|
55
|
+
);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** Source paste of `isAnalyticsDocumentUrl` for the generated Studio client. */
|
|
59
|
+
export function analyticsDocumentGuardSource(): string {
|
|
60
|
+
return `const FILTER_SEGMENT = /${FILTER_SEGMENT_SOURCE}/i;
|
|
61
|
+
const CLICK_ID = /${CLICK_ID_SOURCE}/;
|
|
62
|
+
const DOCUMENT_QUERY = ["q", "ordenar", "page", "pagina"];
|
|
63
|
+
|
|
64
|
+
function documentUrl(href) {
|
|
65
|
+
let url;
|
|
66
|
+
try {
|
|
67
|
+
url = new URL(href, "https://site.invalid");
|
|
68
|
+
} catch {
|
|
69
|
+
return true;
|
|
70
|
+
}
|
|
71
|
+
let pageRaw = null;
|
|
72
|
+
for (const [key, value] of url.searchParams) {
|
|
73
|
+
const name = key.toLowerCase();
|
|
74
|
+
if (pageRaw == null && (name === "page" || name === "pagina")) pageRaw = value;
|
|
75
|
+
}
|
|
76
|
+
if (pageRaw != null && pageRaw !== "") {
|
|
77
|
+
const page = Number(pageRaw);
|
|
78
|
+
if (!Number.isInteger(page) || page !== 1) return false;
|
|
79
|
+
}
|
|
80
|
+
const path = url.pathname.replace(/\\/+$/, "").toLowerCase() || "/";
|
|
81
|
+
if (path !== "/imoveis" && !path.startsWith("/imoveis/")) return true;
|
|
82
|
+
for (const key of url.searchParams.keys()) {
|
|
83
|
+
const name = key.toLowerCase();
|
|
84
|
+
if (DOCUMENT_QUERY.includes(name) || name.startsWith("utm_") || CLICK_ID.test(name)) continue;
|
|
85
|
+
return false;
|
|
86
|
+
}
|
|
87
|
+
const segments = path.split("/").filter(Boolean).slice(1);
|
|
88
|
+
return segments.every((segment) => !FILTER_SEGMENT.test(segment));
|
|
89
|
+
}`;
|
|
90
|
+
}
|
package/src/analytics.ts
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
* consent, the visitor cookie and the site id, and posts it to `/api/t`.
|
|
5
5
|
* Without that listener (server render, other hosts) nothing is sent.
|
|
6
6
|
*/
|
|
7
|
+
import { isAnalyticsDocumentUrl } from "./analytics-document";
|
|
7
8
|
import { changedPathFilters, type LocationNameTables } from "./search-engine";
|
|
8
9
|
import type { AppliedSearchQuery, Listing, SearchPathFilters } from "./types";
|
|
9
10
|
|
|
@@ -16,11 +17,23 @@ type SiteEventName =
|
|
|
16
17
|
| "listings_impressed"
|
|
17
18
|
| "lead_generated";
|
|
18
19
|
|
|
20
|
+
function browserPageHref(): string | null {
|
|
21
|
+
if (typeof window === "undefined") return null;
|
|
22
|
+
const location = (window as { location?: { href?: unknown } }).location;
|
|
23
|
+
return typeof location?.href === "string" ? location.href : null;
|
|
24
|
+
}
|
|
25
|
+
|
|
19
26
|
function emitSiteEvent(
|
|
20
27
|
event: SiteEventName,
|
|
21
28
|
properties: Record<string, unknown>
|
|
22
29
|
): void {
|
|
23
30
|
if (typeof window === "undefined") return;
|
|
31
|
+
const href = browserPageHref();
|
|
32
|
+
// A lead on a filter URL is still a conversion. Everything else on a
|
|
33
|
+
// crawl URL is not a visit — the installed client drops the pageview too.
|
|
34
|
+
if (href && event !== "lead_generated" && !isAnalyticsDocumentUrl(href)) {
|
|
35
|
+
return;
|
|
36
|
+
}
|
|
24
37
|
window.dispatchEvent(
|
|
25
38
|
new CustomEvent(SITE_ANALYTICS_EVENT, { detail: { event, properties } })
|
|
26
39
|
);
|
package/src/index.ts
CHANGED
|
@@ -85,6 +85,10 @@ export {
|
|
|
85
85
|
export { getShareLink, type GetShareLinkOptions } from "./share";
|
|
86
86
|
|
|
87
87
|
export { SITE_ANALYTICS_EVENT, trackListingView } from "./analytics";
|
|
88
|
+
export {
|
|
89
|
+
analyticsDocumentGuardSource,
|
|
90
|
+
isAnalyticsDocumentUrl,
|
|
91
|
+
} from "./analytics-document";
|
|
88
92
|
|
|
89
93
|
export type {
|
|
90
94
|
ShareEntityType,
|
|
@@ -292,6 +296,8 @@ export {
|
|
|
292
296
|
studioAmenityInstruction,
|
|
293
297
|
studioLeadInstruction,
|
|
294
298
|
studioListingCardInstruction,
|
|
299
|
+
studioDevelopmentCardInstruction,
|
|
300
|
+
developmentCardPublished,
|
|
295
301
|
studioListingDetailInstruction,
|
|
296
302
|
studioPhotoInstruction,
|
|
297
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/studio-contract.ts
CHANGED
|
@@ -158,6 +158,9 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
158
158
|
// `unknownSearchLocation` is in git. Prompts inline the same check with
|
|
159
159
|
// `parseSearchPublicPath` + `locationsPath` until this name is on the pin.
|
|
160
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",
|
|
161
164
|
] as const,
|
|
162
165
|
/**
|
|
163
166
|
* maps.fndn.ai helpers (static map, street view, boundaries, travel
|
|
@@ -250,6 +253,14 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
250
253
|
*/
|
|
251
254
|
analyticsExports: ["trackListingView"] as const,
|
|
252
255
|
analyticsSince: "0.13.0",
|
|
256
|
+
/**
|
|
257
|
+
* Development cards (`model.unitCount`, "A partir de" on `priceLabel`).
|
|
258
|
+
* The search API can return `listing.development` before this pin.
|
|
259
|
+
* Prompts must not name `unitCount` until `minNpmVersion` reaches
|
|
260
|
+
* `developmentCardSince` — v0 copies the field and an older
|
|
261
|
+
* `toListingCardModel` does not set it.
|
|
262
|
+
*/
|
|
263
|
+
developmentCardSince: "0.14.0",
|
|
253
264
|
} as const;
|
|
254
265
|
|
|
255
266
|
export type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
|
|
@@ -446,9 +457,30 @@ export function studioLeadInstruction(): string {
|
|
|
446
457
|
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.`;
|
|
447
458
|
}
|
|
448
459
|
|
|
449
|
-
export function
|
|
460
|
+
export function developmentCardPublished(
|
|
461
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
462
|
+
): boolean {
|
|
463
|
+
return compareSemver(pin, STUDIO_SDK_CONTRACT.developmentCardSince) >= 0;
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
/**
|
|
467
|
+
* How a generated card renders a collapsed development. Empty until the
|
|
468
|
+
* pin ships `toListingCardModel`'s `unitCount`.
|
|
469
|
+
*/
|
|
470
|
+
export function studioDevelopmentCardInstruction(
|
|
471
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
472
|
+
): string {
|
|
473
|
+
if (!developmentCardPublished(pin)) return "";
|
|
474
|
+
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.`;
|
|
475
|
+
}
|
|
476
|
+
|
|
477
|
+
export function studioListingCardInstruction(
|
|
478
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
479
|
+
): string {
|
|
450
480
|
const names = STUDIO_SDK_CONTRACT.listingCardExports.join(", ");
|
|
451
|
-
|
|
481
|
+
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.`;
|
|
482
|
+
const development = studioDevelopmentCardInstruction(pin);
|
|
483
|
+
return development ? `${base}\n\n${development}` : base;
|
|
452
484
|
}
|
|
453
485
|
|
|
454
486
|
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
|
/**
|