@garagem-ai/site-sdk 0.14.1 → 0.15.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/react.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { k as SearchUi, a as Listing, ai as LocationNameTables, S as SearchPathFilters, A as AppliedSearchQuery, bq as MapSearchSubscription, an as MapBounds, as as MapPolygon, au as MapSearchResult, ar as MapPinCluster, O as PhotoSearchItem, U as ListingWithMatchedPhoto, F as FetchLike } from './types-photo-search--3fBk3Cs.mjs';
1
+ import { k as SearchUi, a as Listing, ai as LocationNameTables, S as SearchPathFilters, A as AppliedSearchQuery, bq as MapSearchSubscription, an as MapBounds, as as MapPolygon, au as MapSearchResult, ar as MapPinCluster, O as PhotoSearchItem, U as ListingWithMatchedPhoto, F as FetchLike } from './types-photo-search-BqKzj97S.mjs';
2
2
 
3
3
  type SiteIdInput = string | Promise<string> | (() => string | Promise<string>);
4
4
  type PublicSearchSnapshot = {
package/dist/react.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { k as SearchUi, a as Listing, ai as LocationNameTables, S as SearchPathFilters, A as AppliedSearchQuery, bq as MapSearchSubscription, an as MapBounds, as as MapPolygon, au as MapSearchResult, ar as MapPinCluster, O as PhotoSearchItem, U as ListingWithMatchedPhoto, F as FetchLike } from './types-photo-search--3fBk3Cs.js';
1
+ import { k as SearchUi, a as Listing, ai as LocationNameTables, S as SearchPathFilters, A as AppliedSearchQuery, bq as MapSearchSubscription, an as MapBounds, as as MapPolygon, au as MapSearchResult, ar as MapPinCluster, O as PhotoSearchItem, U as ListingWithMatchedPhoto, F as FetchLike } from './types-photo-search-BqKzj97S.js';
2
2
 
3
3
  type SiteIdInput = string | Promise<string> | (() => string | Promise<string>);
4
4
  type PublicSearchSnapshot = {
@@ -572,6 +572,33 @@ interface ListingDetail extends Listing {
572
572
  unitsPerFloor?: number;
573
573
  totalUnits?: number;
574
574
  } | null;
575
+ /**
576
+ * Present only when this listing is a primary-market development.
577
+ * Absent on older payloads and on every resale, including a condo.
578
+ * Render `listingDetailModel(listing).development` — do not read this
579
+ * raw object, and do not treat search-card `development.unitCount` as it.
580
+ */
581
+ developmentProfile?: {
582
+ name: string;
583
+ developer?: string;
584
+ /** ISO date `YYYY-MM-DD`. */
585
+ deliveryDate?: string;
586
+ /** ISO date `YYYY-MM-DD`. */
587
+ launchDate?: string;
588
+ towers?: number;
589
+ floors?: number;
590
+ totalUnits?: number;
591
+ typologies: Array<{
592
+ name: string;
593
+ code?: string;
594
+ bedrooms: number;
595
+ bathrooms: number;
596
+ area?: number;
597
+ price: number | null;
598
+ pricePerSqm: number | null;
599
+ availableUnits?: number;
600
+ }>;
601
+ } | null;
575
602
  media: ListingMedia[];
576
603
  }
577
604
  /** Filter / pagination options for `getListings`. */
@@ -572,6 +572,33 @@ interface ListingDetail extends Listing {
572
572
  unitsPerFloor?: number;
573
573
  totalUnits?: number;
574
574
  } | null;
575
+ /**
576
+ * Present only when this listing is a primary-market development.
577
+ * Absent on older payloads and on every resale, including a condo.
578
+ * Render `listingDetailModel(listing).development` — do not read this
579
+ * raw object, and do not treat search-card `development.unitCount` as it.
580
+ */
581
+ developmentProfile?: {
582
+ name: string;
583
+ developer?: string;
584
+ /** ISO date `YYYY-MM-DD`. */
585
+ deliveryDate?: string;
586
+ /** ISO date `YYYY-MM-DD`. */
587
+ launchDate?: string;
588
+ towers?: number;
589
+ floors?: number;
590
+ totalUnits?: number;
591
+ typologies: Array<{
592
+ name: string;
593
+ code?: string;
594
+ bedrooms: number;
595
+ bathrooms: number;
596
+ area?: number;
597
+ price: number | null;
598
+ pricePerSqm: number | null;
599
+ availableUnits?: number;
600
+ }>;
601
+ } | null;
575
602
  media: ListingMedia[];
576
603
  }
577
604
  /** Filter / pagination options for `getListings`. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@garagem-ai/site-sdk",
3
- "version": "0.14.1",
3
+ "version": "0.15.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",
package/src/index.ts CHANGED
@@ -298,6 +298,8 @@ export {
298
298
  studioListingCardInstruction,
299
299
  studioDevelopmentCardInstruction,
300
300
  developmentCardPublished,
301
+ developmentProfilePublished,
302
+ studioDevelopmentProfileInstruction,
301
303
  studioListingDetailInstruction,
302
304
  studioPhotoInstruction,
303
305
  studioPhotoInstructionFor,
@@ -1,3 +1,7 @@
1
+ import {
2
+ listingDevelopmentModel,
3
+ type ListingDevelopmentModel,
4
+ } from "./listing-development";
1
5
  import { listingLocationLabel } from "./listing-card-model";
2
6
  import { listingPublicPath } from "./listing-path";
3
7
  import { formatAreaM2, formatListingPrice } from "./presentation";
@@ -51,6 +55,12 @@ export type ListingDetailModel = {
51
55
  descriptionTruncated: boolean;
52
56
  descriptionToggleLabel: string | null;
53
57
  mediaOverlays: ListingMediaOverlay[];
58
+ /**
59
+ * Lançamento block. Null on a resale, including a condo that has
60
+ * `listing.building`. Search-card `listing.development` is a different
61
+ * field (collapsed unit count) and is not this object.
62
+ */
63
+ development: ListingDevelopmentModel | null;
54
64
  };
55
65
 
56
66
  function finiteNumber(value: unknown): number | null {
@@ -356,7 +366,13 @@ export function listingMediaOverlays(listing: {
356
366
  export function listingDetailModel(
357
367
  listing: Pick<
358
368
  ListingDetail,
359
- "id" | "listingCode" | "path" | "price" | "priceVisibility" | "description"
369
+ | "id"
370
+ | "listingCode"
371
+ | "path"
372
+ | "price"
373
+ | "priceVisibility"
374
+ | "description"
375
+ | "developmentProfile"
360
376
  > & {
361
377
  property?: ListingDetail["property"] | null;
362
378
  location?: ListingLocation | null;
@@ -382,5 +398,6 @@ export function listingDetailModel(
382
398
  : "Ler mais"
383
399
  : null,
384
400
  mediaOverlays: listingMediaOverlays(listing),
401
+ development: listingDevelopmentModel(listing.developmentProfile),
385
402
  };
386
403
  }
@@ -0,0 +1,107 @@
1
+ import { formatListingPrice } from "./presentation";
2
+ import type { ListingDetail } from "./types";
3
+
4
+ export type ListingDevelopmentFact = { label: string; text: string };
5
+ export type ListingDevelopmentTypologyModel = {
6
+ name: string;
7
+ code: string | null;
8
+ availableLabel: string | null;
9
+ specs: string | null;
10
+ priceLabel: string;
11
+ pricePerSqmLabel: string | null;
12
+ };
13
+ export type ListingDevelopmentModel = {
14
+ name: string;
15
+ facts: ListingDevelopmentFact[];
16
+ typologies: ListingDevelopmentTypologyModel[];
17
+ };
18
+
19
+ type Profile = NonNullable<ListingDetail["developmentProfile"]>;
20
+
21
+ function formatDateBR(iso: string): string {
22
+ const match = iso.match(/^(\d{4})-(\d{2})-(\d{2})/);
23
+ if (!match) return iso;
24
+ return `${match[3]}/${match[2]}/${match[1]}`;
25
+ }
26
+
27
+ function countLabel(count: number, singular: string, plural: string): string {
28
+ return `${count} ${count === 1 ? singular : plural}`;
29
+ }
30
+
31
+ function typologySpecs(typology: Profile["typologies"][number]): string | null {
32
+ const parts: string[] = [];
33
+ if (typology.bedrooms > 0) {
34
+ parts.push(countLabel(typology.bedrooms, "quarto", "quartos"));
35
+ }
36
+ if (typology.bathrooms > 0) {
37
+ parts.push(countLabel(typology.bathrooms, "banheiro", "banheiros"));
38
+ }
39
+ if (typology.area != null && typology.area > 0) {
40
+ parts.push(`${Math.round(typology.area)} m²`);
41
+ }
42
+ return parts.length > 0 ? parts.join(" · ") : null;
43
+ }
44
+
45
+ function typologyModel(
46
+ typology: Profile["typologies"][number]
47
+ ): ListingDevelopmentTypologyModel {
48
+ const available =
49
+ typology.availableUnits != null && typology.availableUnits > 0
50
+ ? typology.availableUnits
51
+ : null;
52
+ return {
53
+ name: typology.name,
54
+ code: typology.code?.trim() || null,
55
+ availableLabel:
56
+ available == null
57
+ ? null
58
+ : countLabel(available, "disponível", "disponíveis"),
59
+ specs: typologySpecs(typology),
60
+ priceLabel: formatListingPrice(typology.price),
61
+ pricePerSqmLabel:
62
+ typology.pricePerSqm == null
63
+ ? null
64
+ : `${formatListingPrice(typology.pricePerSqm)}/m²`,
65
+ };
66
+ }
67
+
68
+ function developmentFacts(profile: Profile): ListingDevelopmentFact[] {
69
+ const facts: ListingDevelopmentFact[] = [];
70
+ if (profile.developer) {
71
+ facts.push({ label: "Construtora", text: profile.developer });
72
+ }
73
+ if (profile.deliveryDate) {
74
+ facts.push({
75
+ label: "Data de entrega",
76
+ text: formatDateBR(profile.deliveryDate),
77
+ });
78
+ }
79
+ if (profile.launchDate) {
80
+ facts.push({ label: "Lançamento", text: formatDateBR(profile.launchDate) });
81
+ }
82
+ if (profile.towers != null && profile.towers > 0) {
83
+ facts.push({ label: "Torres", text: String(profile.towers) });
84
+ }
85
+ if (profile.floors != null && profile.floors > 0) {
86
+ facts.push({ label: "Total de andares", text: String(profile.floors) });
87
+ }
88
+ if (profile.totalUnits != null && profile.totalUnits > 0) {
89
+ facts.push({
90
+ label: "Total de unidades",
91
+ text: String(profile.totalUnits),
92
+ });
93
+ }
94
+ return facts;
95
+ }
96
+
97
+ /** Null for a resale, including one that only has a condo name. */
98
+ export function listingDevelopmentModel(
99
+ profile: ListingDetail["developmentProfile"]
100
+ ): ListingDevelopmentModel | null {
101
+ if (!profile) return null;
102
+ const name = profile.name.trim();
103
+ const facts = developmentFacts(profile);
104
+ const typologies = profile.typologies.map(typologyModel);
105
+ if (!name && facts.length === 0 && typologies.length === 0) return null;
106
+ return { name, facts, typologies };
107
+ }
@@ -31,11 +31,12 @@ export const STUDIO_SDK_CONTRACT = {
31
31
  * and lead emitters) shipped in 0.13.0. `property_search` sends a city
32
32
  * or neighborhood only when the site's location table knows it, as of
33
33
  * 0.13.2. Development cards (`model.unitCount`, "A partir de" on a
34
- * public price) shipped in 0.14.0. Search filter helpers
34
+ * public price) shipped in 0.14.0. The listing-detail lançamento
35
+ * block (`model.development`) shipped in 0.15.0. Search filter helpers
35
36
  * (`visibleSearchFilters` / `toolbarFilterIds`) shipped in 0.4.12 and
36
37
  * remain on this pin.
37
38
  */
38
- minNpmVersion: "0.14.0",
39
+ minNpmVersion: "0.15.0",
39
40
  /** Historical: older tarballs inject card CSS when those components mount. */
40
41
  selfInjectSince: "0.4.2",
41
42
  chromeStrategy: "app-owned" as const,
@@ -264,6 +265,14 @@ export const STUDIO_SDK_CONTRACT = {
264
265
  * `toListingCardModel` does not set it.
265
266
  */
266
267
  developmentCardSince: "0.14.0",
268
+ /**
269
+ * Listing-detail lançamento block (`model.development`). The API can
270
+ * return `developmentProfile` before this pin. Prompts must not name
271
+ * `model.development` until `minNpmVersion` reaches
272
+ * `developmentProfileSince` — an older `listingDetailModel` leaves it
273
+ * undefined and a generated page would render an empty section.
274
+ */
275
+ developmentProfileSince: "0.15.0",
267
276
  } as const;
268
277
 
269
278
  export type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
@@ -466,6 +475,23 @@ export function developmentCardPublished(
466
475
  return compareSemver(pin, STUDIO_SDK_CONTRACT.developmentCardSince) >= 0;
467
476
  }
468
477
 
478
+ export function developmentProfilePublished(
479
+ pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
480
+ ): boolean {
481
+ return compareSemver(pin, STUDIO_SDK_CONTRACT.developmentProfileSince) >= 0;
482
+ }
483
+
484
+ /**
485
+ * "Sobre o empreendimento" and "Tipologias disponíveis". Empty until the
486
+ * pin ships `listingDetailModel`'s `development` block.
487
+ */
488
+ export function studioDevelopmentProfileInstruction(
489
+ pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
490
+ ): string {
491
+ if (!developmentProfilePublished(pin)) return "";
492
+ return `Primary-market detail: \`listingDetailModel\` sets \`model.development\` only for a lançamento. When \`model.development\` is null, render neither "Sobre o empreendimento" nor "Tipologias disponíveis" — \`listing.building\` on a resale condo is not a lançamento, and \`listing.development\` on a search card is only the collapsed unit count. When it is set, render "Sobre o empreendimento" with \`model.development.name\` when that string is non-empty, then each \`model.development.facts\` item as \`label\` and \`text\`. Render "Tipologias disponíveis" only when \`model.development.typologies.length\` is greater than 0. Each typology shows \`name\`, \`code\` when set, \`availableLabel\` when set, \`specs\` when set, \`priceLabel\`, and \`pricePerSqmLabel\` when set. Do not fetch typologies from another route.`;
493
+ }
494
+
469
495
  /**
470
496
  * How a generated card renders a collapsed development. Empty until the
471
497
  * pin ships `toListingCardModel`'s `unitCount`.
@@ -486,9 +512,13 @@ export function studioListingCardInstruction(
486
512
  return development ? `${base}\n\n${development}` : base;
487
513
  }
488
514
 
489
- export function studioListingDetailInstruction(): string {
515
+ export function studioListingDetailInstruction(
516
+ pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
517
+ ): string {
490
518
  const names = STUDIO_SDK_CONTRACT.listingDetailExports.join(", ");
491
- return `Listing detail: import ${names} from \`${STUDIO_SDK_PACKAGE}\`. Render \`listingDetailModel\` leaves: \`model.facts[].label\` / \`.text\`, \`model.values[].label\` / \`.text\`, \`model.location.label\` / \`model.location.mapsHref\`, breadcrumb \`.href\` (search prefixes of \`listing.path\`). The preço / sob consulta entry is the primary value; condomínio and IPTU are secondary and omitted when missing. \`model.description\` is the complete string — do not slice. A collapsed disclosure uses a container (max-height or overflow), not a cut of the string. Never interpolate \`model.location\`, \`model.facts\`, \`model.values\`, \`model.breadcrumb\`, or \`model.mediaOverlays\` as a React child. Video/tour: \`model.mediaOverlays\` as hash links (\`#video\` / \`#tour\`); player src is \`embedSrc\`; fullscreen overlay closes with browser back; omit when that overlay is absent. Do not key the page on \`location.hash\`. Similar listings: \`getSimilarListings({ siteId, listingId, baseUrl })\` plus the site listing-card module; hide the section when empty. Do not invent a local recommendation loop.`;
519
+ const base = `Listing detail: import ${names} from \`${STUDIO_SDK_PACKAGE}\`. Render \`listingDetailModel\` leaves: \`model.facts[].label\` / \`.text\`, \`model.values[].label\` / \`.text\`, \`model.location.label\` / \`model.location.mapsHref\`, breadcrumb \`.href\` (search prefixes of \`listing.path\`). The preço / sob consulta entry is the primary value; condomínio and IPTU are secondary and omitted when missing. \`model.description\` is the complete string — do not slice. A collapsed disclosure uses a container (max-height or overflow), not a cut of the string. Never interpolate \`model.location\`, \`model.facts\`, \`model.values\`, \`model.breadcrumb\`, or \`model.mediaOverlays\` as a React child. Video/tour: \`model.mediaOverlays\` as hash links (\`#video\` / \`#tour\`); player src is \`embedSrc\`; fullscreen overlay closes with browser back; omit when that overlay is absent. Do not key the page on \`location.hash\`. Similar listings: \`getSimilarListings({ siteId, listingId, baseUrl })\` plus the site listing-card module; hide the section when empty. Do not invent a local recommendation loop.`;
520
+ const development = studioDevelopmentProfileInstruction(pin);
521
+ return development ? `${base} ${development}` : base;
492
522
  }
493
523
 
494
524
  /**
package/src/types.ts CHANGED
@@ -161,6 +161,33 @@ export interface ListingDetail extends Listing {
161
161
  unitsPerFloor?: number;
162
162
  totalUnits?: number;
163
163
  } | null;
164
+ /**
165
+ * Present only when this listing is a primary-market development.
166
+ * Absent on older payloads and on every resale, including a condo.
167
+ * Render `listingDetailModel(listing).development` — do not read this
168
+ * raw object, and do not treat search-card `development.unitCount` as it.
169
+ */
170
+ developmentProfile?: {
171
+ name: string;
172
+ developer?: string;
173
+ /** ISO date `YYYY-MM-DD`. */
174
+ deliveryDate?: string;
175
+ /** ISO date `YYYY-MM-DD`. */
176
+ launchDate?: string;
177
+ towers?: number;
178
+ floors?: number;
179
+ totalUnits?: number;
180
+ typologies: Array<{
181
+ name: string;
182
+ code?: string;
183
+ bedrooms: number;
184
+ bathrooms: number;
185
+ area?: number;
186
+ price: number | null;
187
+ pricePerSqm: number | null;
188
+ availableUnits?: number;
189
+ }>;
190
+ } | null;
164
191
  media: ListingMedia[];
165
192
  }
166
193