@garagem-ai/site-sdk 0.13.6 → 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.
@@ -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.13.6",
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",
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: isPrivate
78
- ? "Sob consulta"
79
- : formatListingPrice(listing.price, "pt-BR", listing.currency ?? "BRL"),
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
  }
@@ -253,6 +253,14 @@ export const STUDIO_SDK_CONTRACT = {
253
253
  */
254
254
  analyticsExports: ["trackListingView"] as const,
255
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",
256
264
  } as const;
257
265
 
258
266
  export type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
@@ -449,9 +457,30 @@ export function studioLeadInstruction(): string {
449
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.`;
450
458
  }
451
459
 
452
- export function studioListingCardInstruction(): string {
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 {
453
480
  const names = STUDIO_SDK_CONTRACT.listingCardExports.join(", ");
454
- return `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.`;
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;
455
484
  }
456
485
 
457
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
  /**