@garagem-ai/site-sdk 0.12.1 → 0.13.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/index.d.mts +31 -6
- package/dist/index.d.ts +31 -6
- package/dist/index.js +2166 -2098
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2164 -2100
- 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 +298 -192
- package/dist/react.js.map +1 -1
- package/dist/react.mjs +298 -192
- package/dist/react.mjs.map +1 -1
- package/dist/{types-photo-search-Bmf1f1-Y.d.mts → types-photo-search-BPLxl65M.d.mts} +41 -41
- package/dist/{types-photo-search-Bmf1f1-Y.d.ts → types-photo-search-BPLxl65M.d.ts} +41 -41
- package/package.json +1 -1
- package/src/analytics.ts +144 -0
- package/src/index.ts +4 -0
- package/src/leads.ts +7 -2
- package/src/react/public-search-snapshot.ts +17 -0
- package/src/react/use-public-search.ts +30 -1
- package/src/search-engine.ts +15 -0
- package/src/studio-contract.ts +36 -3
|
@@ -848,46 +848,6 @@ interface RequestNextOptions {
|
|
|
848
848
|
tags?: string[];
|
|
849
849
|
}
|
|
850
850
|
|
|
851
|
-
/** Fields every listing card must have — no JSX. */
|
|
852
|
-
type ListingCardModel = {
|
|
853
|
-
href: string;
|
|
854
|
-
title: string;
|
|
855
|
-
businessType: ListingBusinessType;
|
|
856
|
-
businessLabel: string;
|
|
857
|
-
priceVisibility: ListingPriceVisibility;
|
|
858
|
-
price: number | null;
|
|
859
|
-
priceLabel: string;
|
|
860
|
-
pricePeriod: string | null;
|
|
861
|
-
locationLabel: string;
|
|
862
|
-
propertyType: string | null;
|
|
863
|
-
coverSrc: string | null;
|
|
864
|
-
coverAlt: string;
|
|
865
|
-
bedrooms: number | null;
|
|
866
|
-
bathrooms: number | null;
|
|
867
|
-
parkingSpaces: number | null;
|
|
868
|
-
areaM2: number | null;
|
|
869
|
-
};
|
|
870
|
-
declare function listingLocationLabel(location: {
|
|
871
|
-
neighborhood?: string | null;
|
|
872
|
-
city?: string | null;
|
|
873
|
-
state?: string | null;
|
|
874
|
-
}): string;
|
|
875
|
-
declare function toListingCardModel(listing: Pick<Listing, "id" | "listingCode" | "path" | "title" | "businessType" | "price" | "currency" | "priceVisibility" | "coverImage"> & {
|
|
876
|
-
property?: {
|
|
877
|
-
type?: string | null;
|
|
878
|
-
bedrooms?: number | null;
|
|
879
|
-
bathrooms?: number | null;
|
|
880
|
-
parkingSpaces?: number | null;
|
|
881
|
-
usableArea?: number | null;
|
|
882
|
-
totalArea?: number | null;
|
|
883
|
-
};
|
|
884
|
-
location?: {
|
|
885
|
-
neighborhood?: string | null;
|
|
886
|
-
city?: string | null;
|
|
887
|
-
state?: string | null;
|
|
888
|
-
};
|
|
889
|
-
}): ListingCardModel;
|
|
890
|
-
|
|
891
851
|
/** Query keys that must never encode filters (Editor/Studio path contract). */
|
|
892
852
|
declare const FORBIDDEN_SEARCH_QUERY_KEYS: readonly ["tipo", "quartos", "tipo-imovel", "banheiros", "vagas"];
|
|
893
853
|
/** Default option: omit `ordenar` (API has no relevance token). */
|
|
@@ -974,6 +934,46 @@ type SearchChromeModel = {
|
|
|
974
934
|
};
|
|
975
935
|
declare function searchChromeModel(schema: SearchUi | null, pathFilters: SearchPathFilters, locationNames?: LocationNameTables | null): SearchChromeModel;
|
|
976
936
|
|
|
937
|
+
/** Fields every listing card must have — no JSX. */
|
|
938
|
+
type ListingCardModel = {
|
|
939
|
+
href: string;
|
|
940
|
+
title: string;
|
|
941
|
+
businessType: ListingBusinessType;
|
|
942
|
+
businessLabel: string;
|
|
943
|
+
priceVisibility: ListingPriceVisibility;
|
|
944
|
+
price: number | null;
|
|
945
|
+
priceLabel: string;
|
|
946
|
+
pricePeriod: string | null;
|
|
947
|
+
locationLabel: string;
|
|
948
|
+
propertyType: string | null;
|
|
949
|
+
coverSrc: string | null;
|
|
950
|
+
coverAlt: string;
|
|
951
|
+
bedrooms: number | null;
|
|
952
|
+
bathrooms: number | null;
|
|
953
|
+
parkingSpaces: number | null;
|
|
954
|
+
areaM2: number | null;
|
|
955
|
+
};
|
|
956
|
+
declare function listingLocationLabel(location: {
|
|
957
|
+
neighborhood?: string | null;
|
|
958
|
+
city?: string | null;
|
|
959
|
+
state?: string | null;
|
|
960
|
+
}): string;
|
|
961
|
+
declare function toListingCardModel(listing: Pick<Listing, "id" | "listingCode" | "path" | "title" | "businessType" | "price" | "currency" | "priceVisibility" | "coverImage"> & {
|
|
962
|
+
property?: {
|
|
963
|
+
type?: string | null;
|
|
964
|
+
bedrooms?: number | null;
|
|
965
|
+
bathrooms?: number | null;
|
|
966
|
+
parkingSpaces?: number | null;
|
|
967
|
+
usableArea?: number | null;
|
|
968
|
+
totalArea?: number | null;
|
|
969
|
+
};
|
|
970
|
+
location?: {
|
|
971
|
+
neighborhood?: string | null;
|
|
972
|
+
city?: string | null;
|
|
973
|
+
state?: string | null;
|
|
974
|
+
};
|
|
975
|
+
}): ListingCardModel;
|
|
976
|
+
|
|
977
977
|
/**
|
|
978
978
|
* Map search on top of the friendly public listings route.
|
|
979
979
|
*
|
|
@@ -1109,4 +1109,4 @@ type ListingWithMatchedPhoto = Listing & {
|
|
|
1109
1109
|
matchedPhoto: MatchedListingPhoto | null;
|
|
1110
1110
|
};
|
|
1111
1111
|
|
|
1112
|
-
export { type CmsEntryStatus as $, type AppliedSearchQuery as A, type BoundaryCity as B, type CmsCollection as C, type
|
|
1112
|
+
export { type CmsEntryStatus as $, type AppliedSearchQuery as A, type BoundaryCity as B, type CmsCollection as C, type TravelDestination as D, type TravelMode as E, type FetchLike as F, type TravelTimeOptions as G, type TravelTime as H, type TravelTimesOptions as I, type TravelTimeElement as J, type PhotoSearchResult as K, type ListingDetail as L, type MapsCoordinates as M, type NeighborhoodBoundaryOptions as N, type PhotoSearchItem as O, type PhotoSearchParams as P, type QueryListingsFilters as Q, type RequestNextOptions as R, type SearchPathFilters as S, type TravelTimeCacheOptions as T, type ListingWithMatchedPhoto as U, type MatchedListingPhoto as V, type BoundaryFeature as W, type BoundaryFeatureCollection as X, type BoundaryGeometry as Y, type BoundaryLayerUrlKind as Z, type BoundarySourceLayer as _, type Listing as a, hrefForAppliedChange as a$, type CmsFieldDefinition as a0, type CmsFieldType as a1, type CmsSeoData as a2, FORBIDDEN_SEARCH_QUERY_KEYS as a3, GaragemSdkError as a4, type GetCmsCollectionOptions as a5, type GetCmsCollectionsOptions as a6, type GetCmsEntriesOptions as a7, type GetCmsEntryOptions as a8, type GetListingOptions as a9, type SearchChromeModel as aA, type SearchListingsOptions as aB, type SearchPathLocation as aC, type SearchUiFilter as aD, type SearchUiOption as aE, type StaticMapStyle as aF, TOOLBAR_PRIMARY_FILTER_IDS as aG, applyPathFilter as aH, buildQueryListingsParams as aI, canonicalizeSearchHref as aJ, capMapPage as aK, capMapPageSize as aL, clearStagedPathFilters as aM, clusterBuckets as aN, clusterPins as aO, countFacetChoices as aP, countOptionLabel as aQ, displayPathLocation as aR, getCmsCollection as aS, getCmsCollections as aT, getCmsEntries as aU, getCmsEntry as aV, getListing as aW, getListings as aX, getSearchUi as aY, getSimilarListings as aZ, getSite as a_, type GetListingsOptions as aa, type GetSearchUiOptions as ab, type GetSimilarListingsOptions as ac, type GetSiteOptions as ad, type ListingBusinessType as ae, type ListingCardModel as af, type ListingPriceVisibility as ag, type ListingPropertySummary as ah, type LocationNameTables as ai, MAP_POLYGON_MAX_VERTICES as aj, MAP_SEARCH_DEFAULT_PAGE_SIZE as ak, MAP_SEARCH_MAX_PAGE_SIZE as al, MAP_VIEWPORT_DEBOUNCE_MS as am, type MapBounds as an, type MapBoundsSearchOptions as ao, type MapBucket as ap, type MapPin as aq, type MapPinCluster as ar, type MapPolygon as as, type MapPolygonSearchOptions as at, type MapSearchResult as au, type MapsBaseOptions as av, type QueryListingsLocation as aw, type QueryListingsOptions as ax, SEARCH_EMPTY_COPY as ay, SEARCH_SORT_RELEVANCE as az, type ListingLocation as b, hrefForPathFilters as b0, hrefWithExplicitPage as b1, isListingDetailPath as b2, isMapBounds as b3, isMapPolygon as b4, listingLocationLabel as b5, mapClusterCellDegrees as b6, mapSearchPins as b7, paginationPages as b8, pathFilterHasOption as b9, pathFilterValue as ba, publicSearchHref as bb, queryListings as bc, rangeDraftFromPath as bd, readPublicSearch as be, searchChromeModel as bf, searchHrefUsesLegacyFilterQuery as bg, searchListings as bh, searchListingsInBounds as bi, searchListingsInPolygon as bj, searchResultsHeading as bk, searchSortOptions as bl, toListingCardModel as bm, toolbarFilterIds as bn, visibleSearchFilters as bo, type MapSearchSubscription as bp, type ListingMedia as c, type SearchUiDictionary as d, type AppliedSearchChange as e, type ListingFilters as f, type ListingsResult as g, type Site as h, type SearchListingsParams as i, type SearchListingsResult as j, type SearchUi as k, type QueryListingsParams as l, type QueryListingsResult as m, type SimilarListingsResult as n, type CmsEntriesResult as o, type CmsEntry as p, type BoundaryLayerOptions as q, type TravelTimeCache as r, type MapsFetchOptions as s, type BoundaryLayer as t, type ListingWithLocation as u, type StaticMapOptions as v, type StreetViewAvailabilityOptions as w, type StreetViewAvailability as x, type StreetViewOptions as y, type NeighborhoodBoundary as z };
|
|
@@ -848,46 +848,6 @@ interface RequestNextOptions {
|
|
|
848
848
|
tags?: string[];
|
|
849
849
|
}
|
|
850
850
|
|
|
851
|
-
/** Fields every listing card must have — no JSX. */
|
|
852
|
-
type ListingCardModel = {
|
|
853
|
-
href: string;
|
|
854
|
-
title: string;
|
|
855
|
-
businessType: ListingBusinessType;
|
|
856
|
-
businessLabel: string;
|
|
857
|
-
priceVisibility: ListingPriceVisibility;
|
|
858
|
-
price: number | null;
|
|
859
|
-
priceLabel: string;
|
|
860
|
-
pricePeriod: string | null;
|
|
861
|
-
locationLabel: string;
|
|
862
|
-
propertyType: string | null;
|
|
863
|
-
coverSrc: string | null;
|
|
864
|
-
coverAlt: string;
|
|
865
|
-
bedrooms: number | null;
|
|
866
|
-
bathrooms: number | null;
|
|
867
|
-
parkingSpaces: number | null;
|
|
868
|
-
areaM2: number | null;
|
|
869
|
-
};
|
|
870
|
-
declare function listingLocationLabel(location: {
|
|
871
|
-
neighborhood?: string | null;
|
|
872
|
-
city?: string | null;
|
|
873
|
-
state?: string | null;
|
|
874
|
-
}): string;
|
|
875
|
-
declare function toListingCardModel(listing: Pick<Listing, "id" | "listingCode" | "path" | "title" | "businessType" | "price" | "currency" | "priceVisibility" | "coverImage"> & {
|
|
876
|
-
property?: {
|
|
877
|
-
type?: string | null;
|
|
878
|
-
bedrooms?: number | null;
|
|
879
|
-
bathrooms?: number | null;
|
|
880
|
-
parkingSpaces?: number | null;
|
|
881
|
-
usableArea?: number | null;
|
|
882
|
-
totalArea?: number | null;
|
|
883
|
-
};
|
|
884
|
-
location?: {
|
|
885
|
-
neighborhood?: string | null;
|
|
886
|
-
city?: string | null;
|
|
887
|
-
state?: string | null;
|
|
888
|
-
};
|
|
889
|
-
}): ListingCardModel;
|
|
890
|
-
|
|
891
851
|
/** Query keys that must never encode filters (Editor/Studio path contract). */
|
|
892
852
|
declare const FORBIDDEN_SEARCH_QUERY_KEYS: readonly ["tipo", "quartos", "tipo-imovel", "banheiros", "vagas"];
|
|
893
853
|
/** Default option: omit `ordenar` (API has no relevance token). */
|
|
@@ -974,6 +934,46 @@ type SearchChromeModel = {
|
|
|
974
934
|
};
|
|
975
935
|
declare function searchChromeModel(schema: SearchUi | null, pathFilters: SearchPathFilters, locationNames?: LocationNameTables | null): SearchChromeModel;
|
|
976
936
|
|
|
937
|
+
/** Fields every listing card must have — no JSX. */
|
|
938
|
+
type ListingCardModel = {
|
|
939
|
+
href: string;
|
|
940
|
+
title: string;
|
|
941
|
+
businessType: ListingBusinessType;
|
|
942
|
+
businessLabel: string;
|
|
943
|
+
priceVisibility: ListingPriceVisibility;
|
|
944
|
+
price: number | null;
|
|
945
|
+
priceLabel: string;
|
|
946
|
+
pricePeriod: string | null;
|
|
947
|
+
locationLabel: string;
|
|
948
|
+
propertyType: string | null;
|
|
949
|
+
coverSrc: string | null;
|
|
950
|
+
coverAlt: string;
|
|
951
|
+
bedrooms: number | null;
|
|
952
|
+
bathrooms: number | null;
|
|
953
|
+
parkingSpaces: number | null;
|
|
954
|
+
areaM2: number | null;
|
|
955
|
+
};
|
|
956
|
+
declare function listingLocationLabel(location: {
|
|
957
|
+
neighborhood?: string | null;
|
|
958
|
+
city?: string | null;
|
|
959
|
+
state?: string | null;
|
|
960
|
+
}): string;
|
|
961
|
+
declare function toListingCardModel(listing: Pick<Listing, "id" | "listingCode" | "path" | "title" | "businessType" | "price" | "currency" | "priceVisibility" | "coverImage"> & {
|
|
962
|
+
property?: {
|
|
963
|
+
type?: string | null;
|
|
964
|
+
bedrooms?: number | null;
|
|
965
|
+
bathrooms?: number | null;
|
|
966
|
+
parkingSpaces?: number | null;
|
|
967
|
+
usableArea?: number | null;
|
|
968
|
+
totalArea?: number | null;
|
|
969
|
+
};
|
|
970
|
+
location?: {
|
|
971
|
+
neighborhood?: string | null;
|
|
972
|
+
city?: string | null;
|
|
973
|
+
state?: string | null;
|
|
974
|
+
};
|
|
975
|
+
}): ListingCardModel;
|
|
976
|
+
|
|
977
977
|
/**
|
|
978
978
|
* Map search on top of the friendly public listings route.
|
|
979
979
|
*
|
|
@@ -1109,4 +1109,4 @@ type ListingWithMatchedPhoto = Listing & {
|
|
|
1109
1109
|
matchedPhoto: MatchedListingPhoto | null;
|
|
1110
1110
|
};
|
|
1111
1111
|
|
|
1112
|
-
export { type CmsEntryStatus as $, type AppliedSearchQuery as A, type BoundaryCity as B, type CmsCollection as C, type
|
|
1112
|
+
export { type CmsEntryStatus as $, type AppliedSearchQuery as A, type BoundaryCity as B, type CmsCollection as C, type TravelDestination as D, type TravelMode as E, type FetchLike as F, type TravelTimeOptions as G, type TravelTime as H, type TravelTimesOptions as I, type TravelTimeElement as J, type PhotoSearchResult as K, type ListingDetail as L, type MapsCoordinates as M, type NeighborhoodBoundaryOptions as N, type PhotoSearchItem as O, type PhotoSearchParams as P, type QueryListingsFilters as Q, type RequestNextOptions as R, type SearchPathFilters as S, type TravelTimeCacheOptions as T, type ListingWithMatchedPhoto as U, type MatchedListingPhoto as V, type BoundaryFeature as W, type BoundaryFeatureCollection as X, type BoundaryGeometry as Y, type BoundaryLayerUrlKind as Z, type BoundarySourceLayer as _, type Listing as a, hrefForAppliedChange as a$, type CmsFieldDefinition as a0, type CmsFieldType as a1, type CmsSeoData as a2, FORBIDDEN_SEARCH_QUERY_KEYS as a3, GaragemSdkError as a4, type GetCmsCollectionOptions as a5, type GetCmsCollectionsOptions as a6, type GetCmsEntriesOptions as a7, type GetCmsEntryOptions as a8, type GetListingOptions as a9, type SearchChromeModel as aA, type SearchListingsOptions as aB, type SearchPathLocation as aC, type SearchUiFilter as aD, type SearchUiOption as aE, type StaticMapStyle as aF, TOOLBAR_PRIMARY_FILTER_IDS as aG, applyPathFilter as aH, buildQueryListingsParams as aI, canonicalizeSearchHref as aJ, capMapPage as aK, capMapPageSize as aL, clearStagedPathFilters as aM, clusterBuckets as aN, clusterPins as aO, countFacetChoices as aP, countOptionLabel as aQ, displayPathLocation as aR, getCmsCollection as aS, getCmsCollections as aT, getCmsEntries as aU, getCmsEntry as aV, getListing as aW, getListings as aX, getSearchUi as aY, getSimilarListings as aZ, getSite as a_, type GetListingsOptions as aa, type GetSearchUiOptions as ab, type GetSimilarListingsOptions as ac, type GetSiteOptions as ad, type ListingBusinessType as ae, type ListingCardModel as af, type ListingPriceVisibility as ag, type ListingPropertySummary as ah, type LocationNameTables as ai, MAP_POLYGON_MAX_VERTICES as aj, MAP_SEARCH_DEFAULT_PAGE_SIZE as ak, MAP_SEARCH_MAX_PAGE_SIZE as al, MAP_VIEWPORT_DEBOUNCE_MS as am, type MapBounds as an, type MapBoundsSearchOptions as ao, type MapBucket as ap, type MapPin as aq, type MapPinCluster as ar, type MapPolygon as as, type MapPolygonSearchOptions as at, type MapSearchResult as au, type MapsBaseOptions as av, type QueryListingsLocation as aw, type QueryListingsOptions as ax, SEARCH_EMPTY_COPY as ay, SEARCH_SORT_RELEVANCE as az, type ListingLocation as b, hrefForPathFilters as b0, hrefWithExplicitPage as b1, isListingDetailPath as b2, isMapBounds as b3, isMapPolygon as b4, listingLocationLabel as b5, mapClusterCellDegrees as b6, mapSearchPins as b7, paginationPages as b8, pathFilterHasOption as b9, pathFilterValue as ba, publicSearchHref as bb, queryListings as bc, rangeDraftFromPath as bd, readPublicSearch as be, searchChromeModel as bf, searchHrefUsesLegacyFilterQuery as bg, searchListings as bh, searchListingsInBounds as bi, searchListingsInPolygon as bj, searchResultsHeading as bk, searchSortOptions as bl, toListingCardModel as bm, toolbarFilterIds as bn, visibleSearchFilters as bo, type MapSearchSubscription as bp, type ListingMedia as c, type SearchUiDictionary as d, type AppliedSearchChange as e, type ListingFilters as f, type ListingsResult as g, type Site as h, type SearchListingsParams as i, type SearchListingsResult as j, type SearchUi as k, type QueryListingsParams as l, type QueryListingsResult as m, type SimilarListingsResult as n, type CmsEntriesResult as o, type CmsEntry as p, type BoundaryLayerOptions as q, type TravelTimeCache as r, type MapsFetchOptions as s, type BoundaryLayer as t, type ListingWithLocation as u, type StaticMapOptions as v, type StreetViewAvailabilityOptions as w, type StreetViewAvailability as x, type StreetViewOptions as y, type NeighborhoodBoundary as z };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@garagem-ai/site-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.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/analytics.ts
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Site analytics catalog events. The SDK only announces an event on
|
|
3
|
+
* `window`; the `SiteAnalytics` client that Studio publish installs owns
|
|
4
|
+
* consent, the visitor cookie and the site id, and posts it to `/api/t`.
|
|
5
|
+
* Without that listener (server render, other hosts) nothing is sent.
|
|
6
|
+
*/
|
|
7
|
+
import {
|
|
8
|
+
changedPathFilters,
|
|
9
|
+
displayPathLocation,
|
|
10
|
+
type LocationNameTables,
|
|
11
|
+
} from "./search-engine";
|
|
12
|
+
import type { AppliedSearchQuery, Listing, SearchPathFilters } from "./types";
|
|
13
|
+
|
|
14
|
+
export const SITE_ANALYTICS_EVENT = "garagem:site-event";
|
|
15
|
+
|
|
16
|
+
type SiteEventName =
|
|
17
|
+
| "property_viewed"
|
|
18
|
+
| "property_search"
|
|
19
|
+
| "filter_applied"
|
|
20
|
+
| "listings_impressed"
|
|
21
|
+
| "lead_generated";
|
|
22
|
+
|
|
23
|
+
function emitSiteEvent(
|
|
24
|
+
event: SiteEventName,
|
|
25
|
+
properties: Record<string, unknown>
|
|
26
|
+
): void {
|
|
27
|
+
if (typeof window === "undefined") return;
|
|
28
|
+
window.dispatchEvent(
|
|
29
|
+
new CustomEvent(SITE_ANALYTICS_EVENT, { detail: { event, properties } })
|
|
30
|
+
);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function catalogBusinessType(value: string | undefined) {
|
|
34
|
+
return value === "sale" || value === "rental" ? value : undefined;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function minOf(value: number | number[] | undefined): number | undefined {
|
|
38
|
+
if (!Array.isArray(value)) return value;
|
|
39
|
+
return value.length ? Math.min(...value) : undefined;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Call once per listing page in the browser (an effect keyed on `listing.id`). */
|
|
43
|
+
export function trackListingView(
|
|
44
|
+
listing: Pick<
|
|
45
|
+
Listing,
|
|
46
|
+
"id" | "listingCode" | "businessType" | "property" | "location"
|
|
47
|
+
>
|
|
48
|
+
): void {
|
|
49
|
+
if (!listing?.id) return;
|
|
50
|
+
emitSiteEvent("property_viewed", {
|
|
51
|
+
property_id: listing.id,
|
|
52
|
+
listing_code: listing.listingCode ?? undefined,
|
|
53
|
+
property_type: listing.property?.type || undefined,
|
|
54
|
+
business_type: catalogBusinessType(listing.businessType),
|
|
55
|
+
location_city: listing.location?.city || undefined,
|
|
56
|
+
location_state: listing.location?.state || undefined,
|
|
57
|
+
location_neighborhood: listing.location?.neighborhood || undefined,
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** @internal Emitted by the lead helpers after the webhook accepts the lead. */
|
|
62
|
+
export function trackLeadGenerated(
|
|
63
|
+
leadType: "visit" | "contact",
|
|
64
|
+
listingId: string
|
|
65
|
+
): void {
|
|
66
|
+
emitSiteEvent("lead_generated", {
|
|
67
|
+
lead_type: leadType,
|
|
68
|
+
property_id: listingId,
|
|
69
|
+
form_location: "property_page",
|
|
70
|
+
});
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** @internal Emitted by `usePublicSearch` once per logical search. */
|
|
74
|
+
export function trackSearchResults(input: {
|
|
75
|
+
pathFilters: SearchPathFilters;
|
|
76
|
+
applied: AppliedSearchQuery;
|
|
77
|
+
locationNames: LocationNameTables | null;
|
|
78
|
+
listingIds: string[];
|
|
79
|
+
total: number;
|
|
80
|
+
page: number;
|
|
81
|
+
}): void {
|
|
82
|
+
const { pathFilters, applied, listingIds, page } = input;
|
|
83
|
+
const location = displayPathLocation(
|
|
84
|
+
pathFilters.location,
|
|
85
|
+
input.locationNames
|
|
86
|
+
);
|
|
87
|
+
emitSiteEvent("property_search", {
|
|
88
|
+
query: applied.query || undefined,
|
|
89
|
+
business_type: catalogBusinessType(pathFilters.listingType),
|
|
90
|
+
property_type: pathFilters.propertyType,
|
|
91
|
+
location_city: location?.city,
|
|
92
|
+
location_neighborhood: location?.neighborhood,
|
|
93
|
+
min_price: pathFilters.price?.min,
|
|
94
|
+
max_price: pathFilters.price?.max,
|
|
95
|
+
min_bedrooms: minOf(pathFilters.bedrooms),
|
|
96
|
+
min_area: pathFilters.area?.min,
|
|
97
|
+
max_area: pathFilters.area?.max,
|
|
98
|
+
result_count: input.total,
|
|
99
|
+
page,
|
|
100
|
+
sort_by: applied.sort || undefined,
|
|
101
|
+
});
|
|
102
|
+
if (!listingIds.length) return;
|
|
103
|
+
emitSiteEvent("listings_impressed", {
|
|
104
|
+
property_ids: listingIds,
|
|
105
|
+
impression_count: listingIds.length,
|
|
106
|
+
source: "search",
|
|
107
|
+
page,
|
|
108
|
+
});
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
function filterValue(value: unknown): string | number | boolean | string[] {
|
|
112
|
+
if (
|
|
113
|
+
typeof value === "string" ||
|
|
114
|
+
typeof value === "number" ||
|
|
115
|
+
typeof value === "boolean"
|
|
116
|
+
) {
|
|
117
|
+
return value;
|
|
118
|
+
}
|
|
119
|
+
if (Array.isArray(value)) return value.map(String);
|
|
120
|
+
if (value && typeof value === "object") {
|
|
121
|
+
const { min, max } = value as { min?: unknown; max?: unknown };
|
|
122
|
+
return `${min ?? ""}-${max ?? ""}`;
|
|
123
|
+
}
|
|
124
|
+
return "";
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** @internal Emitted by `usePublicSearch().applyFilter`. */
|
|
128
|
+
export function trackFilterApplied(filterId: string, value: unknown): void {
|
|
129
|
+
emitSiteEvent("filter_applied", {
|
|
130
|
+
filter_name: filterId,
|
|
131
|
+
filter_value: filterValue(value),
|
|
132
|
+
...(value == null ? { filter_action: "clear" } : {}),
|
|
133
|
+
});
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** @internal Emitted by `usePublicSearch().applyStaged`, once per changed filter. */
|
|
137
|
+
export function trackStagedFiltersApplied(
|
|
138
|
+
current: SearchPathFilters,
|
|
139
|
+
staged: SearchPathFilters
|
|
140
|
+
): void {
|
|
141
|
+
for (const { filterId, value } of changedPathFilters(current, staged)) {
|
|
142
|
+
trackFilterApplied(filterId, value);
|
|
143
|
+
}
|
|
144
|
+
}
|
package/src/index.ts
CHANGED
|
@@ -84,6 +84,8 @@ export {
|
|
|
84
84
|
|
|
85
85
|
export { getShareLink, type GetShareLinkOptions } from "./share";
|
|
86
86
|
|
|
87
|
+
export { SITE_ANALYTICS_EVENT, trackListingView } from "./analytics";
|
|
88
|
+
|
|
87
89
|
export type {
|
|
88
90
|
ShareEntityType,
|
|
89
91
|
ShareLinkError,
|
|
@@ -299,6 +301,8 @@ export {
|
|
|
299
301
|
isPhotoSearchOnPin,
|
|
300
302
|
isSellerLeadOnPin,
|
|
301
303
|
isShareLinkOnPin,
|
|
304
|
+
isAnalyticsOnPin,
|
|
305
|
+
studioListingViewInstruction,
|
|
302
306
|
studioSellerLeadSdkInstruction,
|
|
303
307
|
studioShareLinkInstruction,
|
|
304
308
|
studioSdkPinInstruction,
|
package/src/leads.ts
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
* goes to the webhook (`source: "site-sdk"`). v0 draws the dialog.
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
|
+
import { trackLeadGenerated } from "./analytics";
|
|
6
7
|
import { callJson, type FetchLike } from "./fetchers";
|
|
7
8
|
import {
|
|
8
9
|
parseSdkErrorBody,
|
|
@@ -452,7 +453,7 @@ export async function submitVisitLead(
|
|
|
452
453
|
{ code: "invalid_slot" }
|
|
453
454
|
);
|
|
454
455
|
}
|
|
455
|
-
|
|
456
|
+
const result = await postSiteLead({
|
|
456
457
|
siteId: input.siteId,
|
|
457
458
|
baseUrl: input.baseUrl,
|
|
458
459
|
fetch: input.fetch,
|
|
@@ -468,13 +469,15 @@ export async function submitVisitLead(
|
|
|
468
469
|
...prepared.extras,
|
|
469
470
|
},
|
|
470
471
|
});
|
|
472
|
+
trackLeadGenerated("visit", prepared.listingId);
|
|
473
|
+
return result;
|
|
471
474
|
}
|
|
472
475
|
|
|
473
476
|
export async function submitContactLead(
|
|
474
477
|
input: ContactLeadInput
|
|
475
478
|
): Promise<LeadSubmitResult> {
|
|
476
479
|
const prepared = leadPostContext(input);
|
|
477
|
-
|
|
480
|
+
const result = await postSiteLead({
|
|
478
481
|
siteId: input.siteId,
|
|
479
482
|
baseUrl: input.baseUrl,
|
|
480
483
|
fetch: input.fetch,
|
|
@@ -488,4 +491,6 @@ export async function submitContactLead(
|
|
|
488
491
|
...prepared.extras,
|
|
489
492
|
},
|
|
490
493
|
});
|
|
494
|
+
trackLeadGenerated("contact", prepared.listingId);
|
|
495
|
+
return result;
|
|
491
496
|
}
|
|
@@ -140,6 +140,23 @@ export function shouldPreservePaintedListingsOnRefetchFailure(options: {
|
|
|
140
140
|
);
|
|
141
141
|
}
|
|
142
142
|
|
|
143
|
+
/**
|
|
144
|
+
* Catalog search analytics fire once per logical search. A
|
|
145
|
+
* `canonicalizeSearchHref` rewrite of the tracked query refetches listings
|
|
146
|
+
* but must not emit a second `property_search` / `listings_impressed` pair.
|
|
147
|
+
*/
|
|
148
|
+
export function shouldTrackSearchResults(options: {
|
|
149
|
+
trackedSearchKey: string | null;
|
|
150
|
+
searchKey: string;
|
|
151
|
+
dictionary?: SearchUiDictionary;
|
|
152
|
+
}): boolean {
|
|
153
|
+
return !searchKeysRepresentSameQuery(
|
|
154
|
+
options.trackedSearchKey,
|
|
155
|
+
options.searchKey,
|
|
156
|
+
options.dictionary
|
|
157
|
+
);
|
|
158
|
+
}
|
|
159
|
+
|
|
143
160
|
/** Query text already known from the URL, so the field is filled in the SSR HTML. */
|
|
144
161
|
export function initialQueryDraft(
|
|
145
162
|
pathname: string,
|
|
@@ -3,6 +3,11 @@
|
|
|
3
3
|
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
|
|
4
4
|
import { usePathname, useRouter } from "next/navigation";
|
|
5
5
|
|
|
6
|
+
import {
|
|
7
|
+
trackFilterApplied,
|
|
8
|
+
trackSearchResults,
|
|
9
|
+
trackStagedFiltersApplied,
|
|
10
|
+
} from "../analytics";
|
|
6
11
|
import { getSearchUi, queryListings } from "../fetchers";
|
|
7
12
|
import { publishableKeyHeaders } from "../internal/sdk-http";
|
|
8
13
|
import { coerceSiteId, normalizeBaseUrl } from "../internal/url";
|
|
@@ -30,6 +35,7 @@ import {
|
|
|
30
35
|
shouldClearPaintedSearchOnSchemaFailure,
|
|
31
36
|
shouldPreservePaintedListingsOnRefetchFailure,
|
|
32
37
|
shouldSetLoadingOnSearchKeyChange,
|
|
38
|
+
shouldTrackSearchResults,
|
|
33
39
|
} from "./public-search-snapshot";
|
|
34
40
|
import { StagedFiltersMirror } from "./staged-filters-mirror";
|
|
35
41
|
|
|
@@ -105,6 +111,7 @@ export function usePublicSearch(
|
|
|
105
111
|
}, [parsed.pathFilters, replaceStaged]);
|
|
106
112
|
|
|
107
113
|
const locationsRef = useRef<LocationNameTables | null>(seed.locationNames);
|
|
114
|
+
const trackedSearchKeyRef = useRef<string | null>(null);
|
|
108
115
|
|
|
109
116
|
useEffect(() => {
|
|
110
117
|
if (!schema) return;
|
|
@@ -244,6 +251,23 @@ export function usePublicSearch(
|
|
|
244
251
|
),
|
|
245
252
|
});
|
|
246
253
|
if (!active) return;
|
|
254
|
+
if (
|
|
255
|
+
shouldTrackSearchResults({
|
|
256
|
+
trackedSearchKey: trackedSearchKeyRef.current,
|
|
257
|
+
searchKey,
|
|
258
|
+
dictionary: currentSchema.dictionary,
|
|
259
|
+
})
|
|
260
|
+
) {
|
|
261
|
+
trackedSearchKeyRef.current = searchKey;
|
|
262
|
+
trackSearchResults({
|
|
263
|
+
pathFilters,
|
|
264
|
+
applied,
|
|
265
|
+
locationNames: locationsRef.current,
|
|
266
|
+
listingIds: (response.listings || []).map((listing) => listing.id),
|
|
267
|
+
total: response.total || 0,
|
|
268
|
+
page: response.page || 1,
|
|
269
|
+
});
|
|
270
|
+
}
|
|
247
271
|
setListings(response.listings || []);
|
|
248
272
|
setPage(response.page || 1);
|
|
249
273
|
setTotal(response.total || 0);
|
|
@@ -287,6 +311,7 @@ export function usePublicSearch(
|
|
|
287
311
|
const applyFilter = useCallback(
|
|
288
312
|
(filterId: string, value: unknown) => {
|
|
289
313
|
if (!schema) return;
|
|
314
|
+
trackFilterApplied(filterId, value);
|
|
290
315
|
go(
|
|
291
316
|
hrefForPathFilters(
|
|
292
317
|
pathname,
|
|
@@ -312,6 +337,10 @@ export function usePublicSearch(
|
|
|
312
337
|
|
|
313
338
|
const applyStaged = useCallback(() => {
|
|
314
339
|
if (!schema) return;
|
|
340
|
+
trackStagedFiltersApplied(
|
|
341
|
+
parsed.pathFilters,
|
|
342
|
+
stagedMirrorRef.current.value
|
|
343
|
+
);
|
|
315
344
|
go(
|
|
316
345
|
hrefForPathFilters(
|
|
317
346
|
pathname,
|
|
@@ -320,7 +349,7 @@ export function usePublicSearch(
|
|
|
320
349
|
stagedMirrorRef.current.value
|
|
321
350
|
)
|
|
322
351
|
);
|
|
323
|
-
}, [go, pathname, search, schema]);
|
|
352
|
+
}, [go, pathname, search, schema, parsed.pathFilters]);
|
|
324
353
|
|
|
325
354
|
const clearStaged = useCallback(() => {
|
|
326
355
|
setStagedState(stagedMirrorRef.current.clear());
|
package/src/search-engine.ts
CHANGED
|
@@ -225,6 +225,21 @@ export function applyPathFilter(
|
|
|
225
225
|
return next;
|
|
226
226
|
}
|
|
227
227
|
|
|
228
|
+
/** Filter ids whose path value differs between two filter sets, with the new value. */
|
|
229
|
+
export function changedPathFilters(
|
|
230
|
+
current: SearchPathFilters,
|
|
231
|
+
next: SearchPathFilters
|
|
232
|
+
): Array<{ filterId: string; value: unknown }> {
|
|
233
|
+
const changed: Array<{ filterId: string; value: unknown }> = [];
|
|
234
|
+
for (const [filterId, key] of Object.entries(PATH_FILTER_IDS)) {
|
|
235
|
+
const before = current?.[key];
|
|
236
|
+
const after = next?.[key];
|
|
237
|
+
if (JSON.stringify(before) === JSON.stringify(after)) continue;
|
|
238
|
+
changed.push({ filterId, value: after });
|
|
239
|
+
}
|
|
240
|
+
return changed;
|
|
241
|
+
}
|
|
242
|
+
|
|
228
243
|
export function pathFilterValue(
|
|
229
244
|
pathFilters: SearchPathFilters | undefined,
|
|
230
245
|
filterId: string
|
package/src/studio-contract.ts
CHANGED
|
@@ -25,10 +25,12 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
25
25
|
* does not export them. Property registration shipped in 0.10.0.
|
|
26
26
|
* Weighted map buckets (`map.buckets`, clustered by the hook) shipped
|
|
27
27
|
* in 0.11.0. Share links (`getShareLink`, `/p/[token]`) shipped in
|
|
28
|
-
* 0.12.0.
|
|
29
|
-
*
|
|
28
|
+
* 0.12.0. Analytics catalog events (`trackListingView` plus the search
|
|
29
|
+
* and lead emitters) shipped in 0.13.0. Search filter helpers
|
|
30
|
+
* (`visibleSearchFilters` / `toolbarFilterIds`) shipped in 0.4.12 and
|
|
31
|
+
* remain on this pin.
|
|
30
32
|
*/
|
|
31
|
-
minNpmVersion: "0.
|
|
33
|
+
minNpmVersion: "0.13.0",
|
|
32
34
|
/** Historical: older tarballs inject card CSS when those components mount. */
|
|
33
35
|
selfInjectSince: "0.4.2",
|
|
34
36
|
chromeStrategy: "app-owned" as const,
|
|
@@ -236,6 +238,14 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
236
238
|
*/
|
|
237
239
|
shareExports: ["getShareLink"] as const,
|
|
238
240
|
shareLinkSince: "0.12.0",
|
|
241
|
+
/**
|
|
242
|
+
* Listing-view analytics. Search and lead catalog events need no prompt:
|
|
243
|
+
* `usePublicSearch` and the lead helpers emit them from `analyticsSince`.
|
|
244
|
+
* Below it `studioListingViewInstruction` prints nothing and
|
|
245
|
+
* `studioCodegenContractViolations` flags `trackListingView`.
|
|
246
|
+
*/
|
|
247
|
+
analyticsExports: ["trackListingView"] as const,
|
|
248
|
+
analyticsSince: "0.13.0",
|
|
239
249
|
} as const;
|
|
240
250
|
|
|
241
251
|
export type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
|
|
@@ -254,6 +264,22 @@ export function isShareLinkOnPin(
|
|
|
254
264
|
return compareSemver(pin, STUDIO_SDK_CONTRACT.shareLinkSince) >= 0;
|
|
255
265
|
}
|
|
256
266
|
|
|
267
|
+
/** Whether the pinned tarball emits catalog analytics events. */
|
|
268
|
+
export function isAnalyticsOnPin(
|
|
269
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
270
|
+
): boolean {
|
|
271
|
+
return compareSemver(pin, STUDIO_SDK_CONTRACT.analyticsSince) >= 0;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/** Listing-detail view event. Empty below `analyticsSince`. */
|
|
275
|
+
export function studioListingViewInstruction(
|
|
276
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
277
|
+
): string {
|
|
278
|
+
if (!isAnalyticsOnPin(pin)) return "";
|
|
279
|
+
const name = STUDIO_SDK_CONTRACT.analyticsExports[0];
|
|
280
|
+
return `Listing view analytics: import ${name} from \`${STUDIO_SDK_PACKAGE}\` in a client component the listing page already renders (the visit/contact component is the usual place) and call \`useEffect(() => { ${name}(listing); }, [listing.id])\`. Call it once per listing page, never in a card, carousel or similar-listings loop. Do not build or post the event yourself.`;
|
|
281
|
+
}
|
|
282
|
+
|
|
257
283
|
/**
|
|
258
284
|
* Native `/p/[token]` page. Empty below `shareLinkSince`, so the current
|
|
259
285
|
* Studio prompt does not mention `getShareLink`.
|
|
@@ -635,6 +661,13 @@ export function studioCodegenContractViolations(text: string): string[] {
|
|
|
635
661
|
}
|
|
636
662
|
}
|
|
637
663
|
}
|
|
664
|
+
if (!isAnalyticsOnPin()) {
|
|
665
|
+
for (const name of STUDIO_SDK_CONTRACT.analyticsExports) {
|
|
666
|
+
if (mentionsExportName(text, name) && !violations.includes(name)) {
|
|
667
|
+
violations.push(name);
|
|
668
|
+
}
|
|
669
|
+
}
|
|
670
|
+
}
|
|
638
671
|
const pin = STUDIO_SDK_CONTRACT.minNpmVersion;
|
|
639
672
|
if (!marketExportsAvailableAt(pin)) {
|
|
640
673
|
for (const name of STUDIO_SDK_CONTRACT.marketExports) {
|