@garagem-ai/site-sdk 0.9.0 → 0.10.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.d.mts +135 -13
- package/dist/index.d.ts +135 -13
- package/dist/index.js +436 -69
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +423 -69
- package/dist/index.mjs.map +1 -1
- package/dist/react.d.mts +1 -1
- package/dist/react.d.ts +1 -1
- package/dist/react.js +4 -4
- package/dist/react.js.map +1 -1
- package/dist/react.mjs +4 -4
- package/dist/react.mjs.map +1 -1
- package/dist/{types-photo-search-D88oevZv.d.mts → types-photo-search-DIoV75SN.d.mts} +1 -1
- package/dist/{types-photo-search-D88oevZv.d.ts → types-photo-search-DIoV75SN.d.ts} +1 -1
- package/package.json +2 -2
- package/src/index.ts +24 -0
- package/src/leads.ts +47 -3
- package/src/map-search.ts +9 -5
- package/src/seller-lead.ts +428 -0
- package/src/studio-contract.ts +71 -11
package/src/studio-contract.ts
CHANGED
|
@@ -20,11 +20,13 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
20
20
|
* this and move that release's names from `optionalReactExports` /
|
|
21
21
|
* `unpublishedSearchExports` / `unpublishedPhoneExports` into the
|
|
22
22
|
* prompt-safe lists. Do not bump here until that tarball is on npm.
|
|
23
|
-
* Phone mask helpers shipped in 0.6.0.
|
|
23
|
+
* Phone mask helpers shipped in 0.6.0. Map search
|
|
24
|
+
* (`useMapSearch`, `searchListingsInBounds`) shipped in 0.9.0 — 0.7.0
|
|
25
|
+
* does not export them. Search filter helpers
|
|
24
26
|
* (`visibleSearchFilters` / `toolbarFilterIds`) shipped in 0.4.12 and
|
|
25
27
|
* remain on this pin.
|
|
26
28
|
*/
|
|
27
|
-
minNpmVersion: "0.
|
|
29
|
+
minNpmVersion: "0.9.0",
|
|
28
30
|
/** Historical: older tarballs inject card CSS when those components mount. */
|
|
29
31
|
selfInjectSince: "0.4.2",
|
|
30
32
|
chromeStrategy: "app-owned" as const,
|
|
@@ -38,6 +40,7 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
38
40
|
*/
|
|
39
41
|
optionalReactExports: {
|
|
40
42
|
usePublicPhotoSearch: "0.7.0",
|
|
43
|
+
useMapSearch: "0.9.0",
|
|
41
44
|
} as Record<string, string>,
|
|
42
45
|
/**
|
|
43
46
|
* Former `/react` chrome (including card/skeleton inject). Completeness
|
|
@@ -148,14 +151,15 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
148
151
|
] as const,
|
|
149
152
|
/**
|
|
150
153
|
* maps.fndn.ai helpers (static map, street view, boundaries, travel
|
|
151
|
-
* time) plus friendly map search. They ship in `mapsSince
|
|
152
|
-
* `studioMapsInstruction()`
|
|
153
|
-
*
|
|
154
|
-
*
|
|
155
|
-
*
|
|
156
|
-
*
|
|
154
|
+
* time) plus friendly map search. They ship in npm 0.9.0 (`mapsSince`).
|
|
155
|
+
* Listing-detail map guidance stays empty: `studioMapsInstruction()`
|
|
156
|
+
* keeps the listing contract for a later task and Studio does not
|
|
157
|
+
* inject it. Map search is `studioMapSearchInstruction()`, and only
|
|
158
|
+
* the site that opted into list-and-map may include that text.
|
|
159
|
+
* `useMapSearch` is a `/react` hook in `optionalReactExports`; the
|
|
160
|
+
* pin sentence does not name it.
|
|
157
161
|
*/
|
|
158
|
-
mapsSince: "0.
|
|
162
|
+
mapsSince: "0.9.0",
|
|
159
163
|
mapsExports: [
|
|
160
164
|
"listingStaticMapUrl",
|
|
161
165
|
"listingStreetViewUrl",
|
|
@@ -199,10 +203,45 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
199
203
|
"applyMatchedPhotoCover",
|
|
200
204
|
] as const,
|
|
201
205
|
photoSearchSince: "0.7.0",
|
|
206
|
+
/**
|
|
207
|
+
* Seller lead (property registration on `/anunciar-imovel`). Prompt-safe
|
|
208
|
+
* only once `minNpmVersion` reaches `sellerLeadSince`; below it
|
|
209
|
+
* `studioSellerLeadSdkInstruction` prints nothing and
|
|
210
|
+
* `studioCodegenContractViolations` flags the names.
|
|
211
|
+
*/
|
|
212
|
+
sellerLeadExports: [
|
|
213
|
+
"submitSellerLead",
|
|
214
|
+
"uploadSellerLeadPhoto",
|
|
215
|
+
"sellerAddressErrors",
|
|
216
|
+
"sellerPhotoSchedule",
|
|
217
|
+
"isValidEmail",
|
|
218
|
+
"isValidName",
|
|
219
|
+
] as const,
|
|
220
|
+
sellerLeadSince: "0.10.0",
|
|
202
221
|
} as const;
|
|
203
222
|
|
|
204
223
|
export type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
|
|
205
224
|
|
|
225
|
+
/** Whether the pinned tarball carries the seller-lead surface. */
|
|
226
|
+
export function isSellerLeadOnPin(
|
|
227
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
228
|
+
): boolean {
|
|
229
|
+
return compareSemver(pin, STUDIO_SDK_CONTRACT.sellerLeadSince) >= 0;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* Fixed SDK half of the property-registration page. The configured fields
|
|
234
|
+
* and photo options come from the Studio onboarding block. Empty below
|
|
235
|
+
* `sellerLeadSince`, so no prompt names an identifier v0 cannot import.
|
|
236
|
+
*/
|
|
237
|
+
export function studioSellerLeadSdkInstruction(
|
|
238
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
239
|
+
): string {
|
|
240
|
+
if (!isSellerLeadOnPin(pin)) return "";
|
|
241
|
+
const names = STUDIO_SDK_CONTRACT.sellerLeadExports.join(", ");
|
|
242
|
+
return `Property registration (\`/anunciar-imovel\`, client component): import ${names}, isValidPhone, toE164 from \`${STUDIO_SDK_PACKAGE}\`. Address: load Maps JS only through \`<script src="https://maps.fndn.ai/sdk.js?callback=initPlaces" async defer />\` (Places is included; never a Google key, never \`maps.googleapis.com\`), then \`google.maps.places.Autocomplete\` with \`componentRestrictions: { country: "br" }\` and pt-BR. Picking a suggestion fills fullAddress, street, number, neighborhood, city, state (the 2-letter code), postalCode, latitude and longitude from the place; a typed address without a suggestion is not enough. The visitor confirms number or "Sem número", bloco/torre or "Não tem", unidade or "Não tem" (noNumber, noBlocoTorre, noUnidade). Block the next group while \`sellerAddressErrors(address)\` has keys and show each message on its field. Owner: name, email and phone are all required — \`isValidName\`, \`isValidEmail\`, the phone mask with \`isValidPhone(toE164(phone))\`. Photos: \`await uploadSellerLeadPhoto({ siteId, baseUrl: GARAGEM_API_BASE, file, publishableKey })\` per file (JPG/PNG/WEBP, 10MB, up to 30), keep the returned URLs. Photo session: \`const schedule = sellerPhotoSchedule(config)\` and \`slotsForDate(schedule, day)\` for the hours. Submit once with \`await submitSellerLead({ siteId, baseUrl: GARAGEM_API_BASE, publishableKey, owner: { name, email, phone }, address, property: { businessType, saleValue, rentValue, condoFee, totalArea, bedrooms, bathrooms, suites, parkingSpaces }, photos, photoSession: { date, time }, photoSchedule: schedule })\` (omit what the visitor did not fill). Errors are \`LeadSubmitError\`: \`duplicate_property\` → "Este imóvel já está cadastrado. Nossa equipe entrará em contato."; \`invalid_address\` → ask to pick the address again; anything else → a retry message. Disable the submit while pending and show a success state after it resolves. Never POST the leads webhook by hand.`;
|
|
243
|
+
}
|
|
244
|
+
|
|
206
245
|
/** Whether the pinned tarball carries the photo-search surface. */
|
|
207
246
|
export function isPhotoSearchOnPin(
|
|
208
247
|
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
@@ -327,7 +366,10 @@ export function studioPublishableKeyInstruction(): string {
|
|
|
327
366
|
|
|
328
367
|
export function studioSdkPinInstruction(): string {
|
|
329
368
|
const version = STUDIO_SDK_CONTRACT.minNpmVersion;
|
|
330
|
-
|
|
369
|
+
// Base hooks only. Optional hooks (`useMapSearch`, `usePublicPhotoSearch`)
|
|
370
|
+
// are named by the guidance that owns them, so a list-only site never
|
|
371
|
+
// sees the identifier.
|
|
372
|
+
const names = STUDIO_SDK_CONTRACT.reactExports.join(", ");
|
|
331
373
|
return `In \`package.json\` set \`"@garagem-ai/site-sdk": "${version}"\` (exact). Import only these \`${STUDIO_SDK_PACKAGE}/react\` names: ${names}.`;
|
|
332
374
|
}
|
|
333
375
|
|
|
@@ -407,7 +449,18 @@ export function mapsExportsPublished(
|
|
|
407
449
|
export function studioMapsInstruction(options: { pin?: string } = {}): string {
|
|
408
450
|
if (!mapsExportsPublished(options.pin)) return "";
|
|
409
451
|
const names = STUDIO_SDK_CONTRACT.mapsExports.join(", ");
|
|
410
|
-
return `Maps on listing detail: from \`${STUDIO_SDK_PACKAGE}\` import ${names}. \`listing.location.coordinates\` is already masked by the site's privacy settings (≈100 m by default) — 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}\` — \`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" />\` — 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 (“quanto tempo até…”): \`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 — a destination the visitor typed, or at most one fixed landmark per listing page — 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
|
|
452
|
+
return `Maps on listing detail: from \`${STUDIO_SDK_PACKAGE}\` import ${names}. \`listing.location.coordinates\` is already masked by the site's privacy settings (≈100 m by default) — 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}\` — \`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" />\` — 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 (“quanto tempo até…”): \`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 — a destination the visitor typed, or at most one fixed landmark per listing page — 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.`;
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
/**
|
|
456
|
+
* Search-page map mode. Empty below `mapsSince`. Studio injects this only
|
|
457
|
+
* when the site chose list and map. Listing-detail helpers stay out of it.
|
|
458
|
+
*/
|
|
459
|
+
export function studioMapSearchInstruction(
|
|
460
|
+
options: { pin?: string } = {}
|
|
461
|
+
): string {
|
|
462
|
+
if (!mapsExportsPublished(options.pin)) return "";
|
|
463
|
+
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 — 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 />\` — 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 — 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. 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. 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. 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.`;
|
|
411
464
|
}
|
|
412
465
|
|
|
413
466
|
/** True when the pinned tarball ships the market-data helpers. */
|
|
@@ -507,6 +560,13 @@ export function studioCodegenContractViolations(text: string): string[] {
|
|
|
507
560
|
}
|
|
508
561
|
}
|
|
509
562
|
}
|
|
563
|
+
if (!isSellerLeadOnPin()) {
|
|
564
|
+
for (const name of STUDIO_SDK_CONTRACT.sellerLeadExports) {
|
|
565
|
+
if (mentionsExportName(text, name) && !violations.includes(name)) {
|
|
566
|
+
violations.push(name);
|
|
567
|
+
}
|
|
568
|
+
}
|
|
569
|
+
}
|
|
510
570
|
const pin = STUDIO_SDK_CONTRACT.minNpmVersion;
|
|
511
571
|
if (!marketExportsAvailableAt(pin)) {
|
|
512
572
|
for (const name of STUDIO_SDK_CONTRACT.marketExports) {
|