@garagem-ai/site-sdk 0.11.0 → 0.12.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.js CHANGED
@@ -97,6 +97,7 @@ __export(src_exports, {
97
97
  getListings: () => getListings,
98
98
  getNeighborhoodSummary: () => getNeighborhoodSummary,
99
99
  getSearchUi: () => getSearchUi,
100
+ getShareLink: () => getShareLink,
100
101
  getSimilarByPhoto: () => getSimilarByPhoto,
101
102
  getSimilarListings: () => getSimilarListings,
102
103
  getSite: () => getSite,
@@ -109,6 +110,7 @@ __export(src_exports, {
109
110
  isMapPolygon: () => isMapPolygon,
110
111
  isPhotoSearchOnPin: () => isPhotoSearchOnPin,
111
112
  isSellerLeadOnPin: () => isSellerLeadOnPin,
113
+ isShareLinkOnPin: () => isShareLinkOnPin,
112
114
  isStudioPreviewHost: () => isStudioPreviewHost,
113
115
  isValidEmail: () => isValidEmail,
114
116
  isValidName: () => isValidName,
@@ -204,6 +206,7 @@ __export(src_exports, {
204
206
  studioSearchInstruction: () => studioSearchInstruction,
205
207
  studioSearchLandmarkInstruction: () => studioSearchLandmarkInstruction,
206
208
  studioSellerLeadSdkInstruction: () => studioSellerLeadSdkInstruction,
209
+ studioShareLinkInstruction: () => studioShareLinkInstruction,
207
210
  studioSiteWidthCss: () => studioSiteWidthCss,
208
211
  submitContactLead: () => submitContactLead,
209
212
  submitSellerLead: () => submitSellerLead,
@@ -660,6 +663,48 @@ async function getCmsEntry(options) {
660
663
  return data;
661
664
  }
662
665
 
666
+ // src/share.ts
667
+ async function getShareLink(options) {
668
+ const { token, password, baseUrl, fetch: fetchImpl, next } = options;
669
+ if (!token || !token.trim()) {
670
+ throw new TypeError("getShareLink: `token` is required");
671
+ }
672
+ const base = normalizeBaseUrl(baseUrl);
673
+ const url = `${base}/api/sites/share/${encodeURIComponent(token)}`;
674
+ const doFetch = fetchImpl ?? fetch;
675
+ const baseInit = password ? {
676
+ method: "POST",
677
+ headers: {
678
+ Accept: "application/json",
679
+ "Content-Type": "application/json"
680
+ },
681
+ body: JSON.stringify({ password }),
682
+ next
683
+ } : { method: "GET", headers: { Accept: "application/json" }, next };
684
+ const init = withPublishableKeyHeader(baseInit, options.publishableKey);
685
+ const response = await doFetch(url, init);
686
+ if (response.ok) {
687
+ return { ok: true, ...await response.json() };
688
+ }
689
+ const EXPECTED_STATUSES = /* @__PURE__ */ new Set([400, 401, 403, 404, 410]);
690
+ if (EXPECTED_STATUSES.has(response.status)) {
691
+ const body = await response.json().catch(() => ({}));
692
+ return {
693
+ ok: false,
694
+ status: response.status,
695
+ reason: body.reason ?? null,
696
+ message: body.error ?? "Share link unavailable",
697
+ ...body.listingCode ? { listingCode: body.listingCode } : {},
698
+ ...body.site ? { site: body.site } : {}
699
+ };
700
+ }
701
+ const text2 = await response.text().catch(() => "");
702
+ throw new GaragemSdkError(
703
+ `Garagem SDK: request failed (${response.status} ${response.statusText}) for ${url}${text2 ? ` \u2014 ${text2.slice(0, 200)}` : ""}`,
704
+ { status: response.status, url }
705
+ );
706
+ }
707
+
663
708
  // src/schedule.ts
664
709
  var VISIT_TIME_ZONE = "America/Sao_Paulo";
665
710
  var HHMM_RE = /^([01]\d|2[0-3]):([0-5]\d)$/;
@@ -3261,10 +3306,11 @@ var STUDIO_SDK_CONTRACT = {
3261
3306
  * Phone mask helpers shipped in 0.6.0. Map search
3262
3307
  * (`useMapSearch`, `searchListingsInBounds`) shipped in 0.9.0 — 0.7.0
3263
3308
  * does not export them. Property registration shipped in 0.10.0.
3264
- * Search filter helpers (`visibleSearchFilters` / `toolbarFilterIds`)
3265
- * shipped in 0.4.12 and remain on this pin.
3309
+ * Weighted map buckets (`map.buckets`, clustered by the hook) shipped
3310
+ * in 0.11.0. Search filter helpers (`visibleSearchFilters` /
3311
+ * `toolbarFilterIds`) shipped in 0.4.12 and remain on this pin.
3266
3312
  */
3267
- minNpmVersion: "0.10.0",
3313
+ minNpmVersion: "0.11.0",
3268
3314
  /** Historical: older tarballs inject card CSS when those components mount. */
3269
3315
  selfInjectSince: "0.4.2",
3270
3316
  chromeStrategy: "app-owned",
@@ -3463,11 +3509,27 @@ var STUDIO_SDK_CONTRACT = {
3463
3509
  "isValidEmail",
3464
3510
  "isValidName"
3465
3511
  ],
3466
- sellerLeadSince: "0.10.0"
3512
+ sellerLeadSince: "0.10.0",
3513
+ /**
3514
+ * Share-link page (`/p/[token]`). Prompt-safe only once `minNpmVersion`
3515
+ * reaches `shareLinkSince`. Below it `studioShareLinkInstruction` prints
3516
+ * nothing and `studioCodegenContractViolations` flags `getShareLink` —
3517
+ * v0 installs the pin and copies any identifier it sees.
3518
+ */
3519
+ shareExports: ["getShareLink"],
3520
+ shareLinkSince: "0.12.0"
3467
3521
  };
3468
3522
  function isSellerLeadOnPin(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
3469
3523
  return compareSemver(pin, STUDIO_SDK_CONTRACT.sellerLeadSince) >= 0;
3470
3524
  }
3525
+ function isShareLinkOnPin(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
3526
+ return compareSemver(pin, STUDIO_SDK_CONTRACT.shareLinkSince) >= 0;
3527
+ }
3528
+ function studioShareLinkInstruction(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
3529
+ if (!isShareLinkOnPin(pin)) return "";
3530
+ const name = STUDIO_SDK_CONTRACT.shareExports[0];
3531
+ return `Share links (\`/p/[token]\`): add a server page \`app/p/[token]/page.tsx\`. Read \`token\` from the route params and \`const result = await ${name}({ token, baseUrl: GARAGEM_API_BASE })\`. When \`result.ok\` is false and \`result.reason\` is \`password_required\` or \`password_invalid\`, render a password form and submit \`getShareLink({ token, password, baseUrl: GARAGEM_API_BASE })\`. For \`not_found\`, \`inactive\`, or \`expired\`, say the link is no longer available \u2014 do not render a generic framework 404. When \`result.ok\` and \`result.listing\` is set, render that listing with the same listing-detail module \`/imoveis\` already uses (\`listingDetailModel\` and the site gallery). Do not invent a second listing layout and do not proxy the page to another host.`;
3532
+ }
3471
3533
  function studioSellerLeadSdkInstruction(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
3472
3534
  if (!isSellerLeadOnPin(pin)) return "";
3473
3535
  const names = STUDIO_SDK_CONTRACT.sellerLeadExports.join(", ");
@@ -3621,11 +3683,21 @@ function studioMapsInstruction(options = {}) {
3621
3683
  const names = STUDIO_SDK_CONTRACT.mapsExports.join(", ");
3622
3684
  return `Maps on listing detail: from \`${STUDIO_SDK_PACKAGE}\` import ${names}. \`listing.location.coordinates\` is already masked by the site's privacy settings (\u2248100 m by default) \u2014 pass the listing object as-is; never un-mask, never re-geocode the street address to get a sharper point, never add decimals (\`maxDecimals\` can only coarsen). Always pass \`siteId\` (the resolved site id / publishable key) so maps.fndn.ai meters the site. Static map: \`const mapSrc = listingStaticMapUrl(listing, { width: 640, height: 320, zoom: 15, style: "roadmap", siteId })\` then \`{mapSrc ? <img src={mapSrc} alt={model.location.label} /> : null}\` \u2014 \`null\` means no coordinates, so omit the block (never a placeholder image). Zoom is capped by the coordinate precision (16 on the default mask); do not work around it. Street View: on the server page \`const sv = await listingStreetViewAvailable(listing, { siteId })\` (metadata is free), and only when \`sv.available\` render \`<img src={listingStreetViewUrl(listing, { width: 640, height: 400, siteId })} alt="Street View" />\` \u2014 the image is billed per load. Neighbourhood outline on an interactive map: load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` (never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`); in \`initMap\` do \`const outline = await neighborhoodBoundaryLayer(listing.location.city, listing.location.neighborhood, { siteId })\` and \`if (outline.feature) map.data.addGeoJson(outline.feature)\`; with MapLibre the vector source url is \`boundaryLayerUrl(listing.location.city)\`. Travel time (\u201Cquanto tempo at\xE9\u2026\u201D): \`const trip = await travelTimeFromListing(listing, destination, { mode: "driving", siteId })\` gives \`{ minutes, distanceKm }\` or \`null\` (hide the row). Every uncached call is a billed Google Directions request: call it on demand \u2014 a destination the visitor typed, or at most one fixed landmark per listing page \u2014 never per listing card, never inside a search loop, keep the SDK cache on (default 15 min LRU, \`cache: null\` only in tests), and do not re-run it on every render.`;
3623
3685
  }
3686
+ var MAP_CLUSTER_MEMBERS_CLICK = "`const members = map.pins.filter((pin) => cluster.pinIds.includes(pin.id))`, then `fitBounds` a LatLngBounds of their coordinates with about 64px padding, so the listings land inside the new view and split into chips.";
3687
+ var MAP_CLUSTER_SAME_POINT = "When every member has the same coordinates, or the map is already at zoom 18, do not zoom: open a small list of those listings, each with its price and a link.";
3688
+ function studioMapClusterClickInstruction(buckets) {
3689
+ if (!buckets) {
3690
+ return `Clicking a cluster opens its members: ${MAP_CLUSTER_MEMBERS_CLICK} Do not step the zoom around \`cluster.lat\`/\`cluster.lng\`: that point is approximate and the area around it can come back empty. ${MAP_CLUSTER_SAME_POINT}`;
3691
+ }
3692
+ return `Clicking a cluster depends on \`cluster.pinIds\`. A cluster with members (\`cluster.pinIds.length > 0\`) opens them: ${MAP_CLUSTER_MEMBERS_CLICK} For such a cluster do not step the zoom around \`cluster.lat\`/\`cluster.lng\`: that point is approximate and the area around it can come back empty. ${MAP_CLUSTER_SAME_POINT} A cluster with empty \`pinIds\` is a bucket and has no members to fit: on click center the map on \`cluster.lat\`/\`cluster.lng\` and zoom in two levels \u2014 the next viewport search returns finer buckets or the listings themselves.`;
3693
+ }
3624
3694
  function studioMapSearchInstruction(options = {}) {
3625
3695
  if (!mapsExportsPublished(options.pin)) return "";
3626
3696
  const pin = options.pin ?? STUDIO_SDK_CONTRACT.minNpmVersion;
3627
- const buckets = compareSemver(pin, STUDIO_SDK_CONTRACT.mapBucketsSince) >= 0 ? " When the matches do not fit on one page, the hook builds `map.clusters` from location buckets whose counts add up to `map.total`; render them as they come and never fetch or merge more pages. A cluster with empty `pinIds` is a bucket: draw it as a cluster, and on click center the map on `cluster.lat`/`cluster.lng` and zoom in two levels \u2014 the next viewport search returns finer buckets or the listings themselves." : "";
3628
- return `Map search on \`/imoveis\` (list and map of the same query). The list stays: keep \`usePublicSearch\` for the list, including its sort and pagination. The visitor switches on the same page. \`?modo=mapa\` is the map \u2014 read it on first paint. The list is the URL without \`modo\`; do not write \`modo=lista\` or \`modo=grade\`. Choosing the map sets \`modo=mapa\` and drops \`page\`. Choosing the list removes \`modo\`. On the map, hide sort and pagination. Do not add a map pager. The heading stays. Filters apply to both. Load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` \u2014 never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`, never \`maps.googleapis.com\`, never \`@vis.gl/react-google-maps\`. From \`${STUDIO_SDK_PACKAGE}/react\` import useMapSearch; it fetches, debounces, and clusters. \`const map = useMapSearch({ siteId, baseUrl: GARAGEM_API_BASE, bounds, zoom, q, sort, location, filters, publishableKey })\` with the same q, sort, location, filters, and publishableKey as the list. Pass the map's current zoom on every zoom change, including after a cluster click. Changing zoom recomputes \`map.clusters\` and does not refetch; a bounds change refetches. Do not send filter_by, vector_query, or nl_query from the browser. Request page 1 and pageSize at most 100. Do not walk totalPages. Pins are the masked coordinates the API returned \u2014 plot them as returned, never geocode the street. Render \`map.clusters\` with \`google.maps.Marker\` (no map id needed), in two styles that never look alike. A cluster (\`count > 1\`) is a filled circle in the brand color with a white border and the white count as its label. A listing (\`count === 1\` with \`cluster.pin\`) is a white rounded-rectangle chip with a brand-color border, labelled with the short price in the brand color ("R$ 850 mil", "R$ 1,2 mi"; "Consulte" when the price is null or 0): \`icon: { path: "M-34,-12 h68 a6,6 0 0 1 6,6 v12 a6,6 0 0 1 -6,6 h-68 a6,6 0 0 1 -6,-6 v-12 a6,6 0 0 1 6,-6 z", fillColor: "#ffffff", fillOpacity: 1, strokeColor: brand, strokeWeight: 1.5, scale: 1, labelOrigin: new google.maps.Point(0, 0) }\`. Never draw a listing as a dot or a circle, and never without its price. Clicking a listing selects it and shows its card. The card content is \`toListingCardModel(map.listings.find((listing) => listing.id === pin.id))\` and shows, in order: a large cover (\`coverSrc\`, aspect 4/3, full card width), title, \`priceLabel\`, \`locationLabel\`, then the facts that are present: \`bedrooms\` quartos, \`bathrooms\` banheiros, \`parkingSpaces\` vagas, \`areaM2\` m\xB2. Title and price alone are incomplete. On a wide screen the card opens next to its pin, never at the bottom of the map, where it falls below the viewport when the page is scrolled. Use one \`google.maps.InfoWindow\` and open it on the clicked marker: \`infoWindow.open({ map: googleMap, anchor: marker })\`. Its content is a div that React fills with \`createPortal\`. The InfoWindow pans the map so the card is in view. On a narrow screen the same card sits in a bottom sheet across the map width. Dismissing it leaves the pins. While \`map.loading\` the map is \`aria-busy\` with a visible progress indicator and the previous pins stay mounted. Clicking a cluster opens its members: \`const members = map.pins.filter((pin) => cluster.pinIds.includes(pin.id))\`, then \`fitBounds\` a LatLngBounds of their coordinates with about 64px padding, so the listings land inside the new view and split into chips. Do not step the zoom around \`cluster.lat\`/\`cluster.lng\`: that point is approximate and the area around it can come back empty. When every member has the same coordinates, or the map is already at zoom 18, do not zoom: open a small list of those listings, each with its price and a link. Layout, top to bottom: query, heading, toolbar, then the view. Lista and Mapa are icon buttons with the site tooltip and \`aria-label\` \u201CLista\u201D / \u201CMapa\u201D, not icon-plus-text. On desktop the toolbar is one row: featured filters on the left, and the list/map toggle immediately beside the sort select on the right. On a narrow screen the filters stay in one horizontal scroll that does not wrap, and the toggle plus the sort sit together on the row below that scroll. That row fits the viewport and never widens the page; sort may truncate. On the map the sort is hidden, so the toggle keeps that place beside where the sort was. In map mode the map fills the remaining viewport height, with a minimum of about 240px. Keep the hook's 400ms viewport debounce. A drawn polygon is not required. Do not add a separate /mapa route, a regions page, or a map on the listing page. Do not call Street View or travel time inside the map search.${buckets}`;
3697
+ const hasBuckets = compareSemver(pin, STUDIO_SDK_CONTRACT.mapBucketsSince) >= 0;
3698
+ const buckets = hasBuckets ? " When the matches do not fit on one page, the hook builds `map.clusters` from location buckets whose counts add up to `map.total`; render them as they come and never fetch or merge more pages. Draw a bucket like any other cluster." : "";
3699
+ const clusterClick = studioMapClusterClickInstruction(hasBuckets);
3700
+ return `Map search on \`/imoveis\` (list and map of the same query). The list stays: keep \`usePublicSearch\` for the list, including its sort and pagination. The visitor switches on the same page. \`?modo=mapa\` is the map \u2014 read it on first paint. The list is the URL without \`modo\`; do not write \`modo=lista\` or \`modo=grade\`. Choosing the map sets \`modo=mapa\` and drops \`page\`. Choosing the list removes \`modo\`. On the map, hide sort and pagination. Do not add a map pager. The heading stays. Filters apply to both. Load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` \u2014 never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`, never \`maps.googleapis.com\`, never \`@vis.gl/react-google-maps\`. From \`${STUDIO_SDK_PACKAGE}/react\` import useMapSearch; it fetches, debounces, and clusters. \`const map = useMapSearch({ siteId, baseUrl: GARAGEM_API_BASE, bounds, zoom, q, sort, location, filters, publishableKey })\` with the same q, sort, location, filters, and publishableKey as the list. Pass the map's current zoom on every zoom change, including after a cluster click. Changing zoom recomputes \`map.clusters\` and does not refetch; a bounds change refetches. Do not send filter_by, vector_query, or nl_query from the browser. Request page 1 and pageSize at most 100. Do not walk totalPages. Pins are the masked coordinates the API returned \u2014 plot them as returned, never geocode the street. Render \`map.clusters\` with \`google.maps.Marker\` (no map id needed), in two styles that never look alike. A cluster (\`count > 1\`) is a filled circle in the brand color with a white border and the white count as its label. A listing (\`count === 1\` with \`cluster.pin\`) is a white rounded-rectangle chip with a brand-color border, labelled with the short price in the brand color ("R$ 850 mil", "R$ 1,2 mi"; "Consulte" when the price is null or 0): \`icon: { path: "M-34,-12 h68 a6,6 0 0 1 6,6 v12 a6,6 0 0 1 -6,6 h-68 a6,6 0 0 1 -6,-6 v-12 a6,6 0 0 1 6,-6 z", fillColor: "#ffffff", fillOpacity: 1, strokeColor: brand, strokeWeight: 1.5, scale: 1, labelOrigin: new google.maps.Point(0, 0) }\`. Never draw a listing as a dot or a circle, and never without its price. Clicking a listing selects it and shows its card. The card content is \`toListingCardModel(map.listings.find((listing) => listing.id === pin.id))\` and shows, in order: a large cover (\`coverSrc\`, aspect 4/3, full card width), title, \`priceLabel\`, \`locationLabel\`, then the facts that are present: \`bedrooms\` quartos, \`bathrooms\` banheiros, \`parkingSpaces\` vagas, \`areaM2\` m\xB2. Title and price alone are incomplete. On a wide screen the card opens next to its pin, never at the bottom of the map, where it falls below the viewport when the page is scrolled. Use one \`google.maps.InfoWindow\` and open it on the clicked marker: \`infoWindow.open({ map: googleMap, anchor: marker })\`. Its content is a div that React fills with \`createPortal\`. The InfoWindow pans the map so the card is in view. On a narrow screen the same card sits in a bottom sheet across the map width. Dismissing it leaves the pins. While \`map.loading\` the map is \`aria-busy\` with a visible progress indicator and the previous pins stay mounted. ${clusterClick} Layout, top to bottom: query, heading, toolbar, then the view. Lista and Mapa are icon buttons with the site tooltip and \`aria-label\` \u201CLista\u201D / \u201CMapa\u201D, not icon-plus-text. On desktop the toolbar is one row: featured filters on the left, and the list/map toggle immediately beside the sort select on the right. On a narrow screen the filters stay in one horizontal scroll that does not wrap, and the toggle plus the sort sit together on the row below that scroll. That row fits the viewport and never widens the page; sort may truncate. On the map the sort is hidden, so the toggle keeps that place beside where the sort was. In map mode the map fills the remaining viewport height, with a minimum of about 240px. Keep the hook's 400ms viewport debounce. A drawn polygon is not required. Do not add a separate /mapa route, a regions page, or a map on the listing page. Do not call Street View or travel time inside the map search.${buckets}`;
3629
3701
  }
3630
3702
  function marketExportsAvailableAt(pin) {
3631
3703
  return compareSemver(pin, STUDIO_SDK_CONTRACT.marketExportsSince) >= 0;
@@ -3703,6 +3775,13 @@ function studioCodegenContractViolations(text2) {
3703
3775
  }
3704
3776
  }
3705
3777
  }
3778
+ if (!isShareLinkOnPin()) {
3779
+ for (const name of STUDIO_SDK_CONTRACT.shareExports) {
3780
+ if (mentionsExportName(text2, name) && !violations.includes(name)) {
3781
+ violations.push(name);
3782
+ }
3783
+ }
3784
+ }
3706
3785
  const pin = STUDIO_SDK_CONTRACT.minNpmVersion;
3707
3786
  if (!marketExportsAvailableAt(pin)) {
3708
3787
  for (const name of STUDIO_SDK_CONTRACT.marketExports) {
@@ -5115,6 +5194,7 @@ function applyMatchedPhotoCover(cards, photoResults, options = {}) {
5115
5194
  getListings,
5116
5195
  getNeighborhoodSummary,
5117
5196
  getSearchUi,
5197
+ getShareLink,
5118
5198
  getSimilarByPhoto,
5119
5199
  getSimilarListings,
5120
5200
  getSite,
@@ -5127,6 +5207,7 @@ function applyMatchedPhotoCover(cards, photoResults, options = {}) {
5127
5207
  isMapPolygon,
5128
5208
  isPhotoSearchOnPin,
5129
5209
  isSellerLeadOnPin,
5210
+ isShareLinkOnPin,
5130
5211
  isStudioPreviewHost,
5131
5212
  isValidEmail,
5132
5213
  isValidName,
@@ -5222,6 +5303,7 @@ function applyMatchedPhotoCover(cards, photoResults, options = {}) {
5222
5303
  studioSearchInstruction,
5223
5304
  studioSearchLandmarkInstruction,
5224
5305
  studioSellerLeadSdkInstruction,
5306
+ studioShareLinkInstruction,
5225
5307
  studioSiteWidthCss,
5226
5308
  submitContactLead,
5227
5309
  submitSellerLead,