@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/README.md +1 -0
- package/dist/index.d.mts +166 -5
- package/dist/index.d.ts +166 -5
- package/dist/index.js +88 -6
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +85 -6
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
- package/src/index.ts +14 -0
- package/src/share.ts +114 -0
- package/src/studio-contract.ts +62 -8
- package/src/types-share.ts +122 -0
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
|
-
*
|
|
3265
|
-
*
|
|
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.
|
|
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
|
|
3628
|
-
|
|
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,
|