@garagem-ai/site-sdk 0.14.1 → 0.15.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/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.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
@@ -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
+ }
@@ -264,6 +264,14 @@ export const STUDIO_SDK_CONTRACT = {
264
264
  * `toListingCardModel` does not set it.
265
265
  */
266
266
  developmentCardSince: "0.14.0",
267
+ /**
268
+ * Listing-detail lançamento block (`model.development`). The API can
269
+ * return `developmentProfile` before this pin. Prompts must not name
270
+ * `model.development` until `minNpmVersion` reaches
271
+ * `developmentProfileSince` — an older `listingDetailModel` leaves it
272
+ * undefined and a generated page would render an empty section.
273
+ */
274
+ developmentProfileSince: "0.15.0",
267
275
  } as const;
268
276
 
269
277
  export type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
@@ -466,6 +474,23 @@ export function developmentCardPublished(
466
474
  return compareSemver(pin, STUDIO_SDK_CONTRACT.developmentCardSince) >= 0;
467
475
  }
468
476
 
477
+ export function developmentProfilePublished(
478
+ pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
479
+ ): boolean {
480
+ return compareSemver(pin, STUDIO_SDK_CONTRACT.developmentProfileSince) >= 0;
481
+ }
482
+
483
+ /**
484
+ * "Sobre o empreendimento" and "Tipologias disponíveis". Empty until the
485
+ * pin ships `listingDetailModel`'s `development` block.
486
+ */
487
+ export function studioDevelopmentProfileInstruction(
488
+ pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
489
+ ): string {
490
+ if (!developmentProfilePublished(pin)) return "";
491
+ 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.`;
492
+ }
493
+
469
494
  /**
470
495
  * How a generated card renders a collapsed development. Empty until the
471
496
  * pin ships `toListingCardModel`'s `unitCount`.
@@ -486,9 +511,13 @@ export function studioListingCardInstruction(
486
511
  return development ? `${base}\n\n${development}` : base;
487
512
  }
488
513
 
489
- export function studioListingDetailInstruction(): string {
514
+ export function studioListingDetailInstruction(
515
+ pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
516
+ ): string {
490
517
  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.`;
518
+ 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.`;
519
+ const development = studioDevelopmentProfileInstruction(pin);
520
+ return development ? `${base} ${development}` : base;
492
521
  }
493
522
 
494
523
  /**
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