@garagem-ai/site-sdk 0.6.1 → 0.7.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.
@@ -0,0 +1,138 @@
1
+ /**
2
+ * Market-data types for the public site.
3
+ *
4
+ * IPTU-module requirement: every market endpoint answers
5
+ * `{ available: false, reason }` (HTTP 200) unless the site's organization
6
+ * holds the IPTU module (`iptu_itbi_integration`), the city is covered and
7
+ * the integration is configured. Render these blocks conditionally on
8
+ * `available`. The payloads carry only aggregates and the trimmed estimate —
9
+ * never comparables, transactions or cadastral identifiers.
10
+ */
11
+
12
+ /** Why a market helper answered `available: false`. */
13
+ export type MarketUnavailableReason =
14
+ /** The organization does not hold the IPTU module (`iptu_itbi_integration`). */
15
+ | "module_not_enabled"
16
+ /** Market-data integration is not configured for this environment. */
17
+ | "not_configured"
18
+ /** The site id does not resolve to an active site. */
19
+ | "site_not_found"
20
+ /** The city is outside the covered-city matrix. */
21
+ | "city_unsupported"
22
+ /** Only sale prices are covered. */
23
+ | "listing_type_unsupported"
24
+ /** Listing price is private or missing. */
25
+ | "price_unavailable"
26
+ /** No usable aggregate for the request. */
27
+ | "no_data"
28
+ /** The SDK was rate limited (HTTP 429); try again later. */
29
+ | "rate_limited";
30
+
31
+ export type MarketPropertyType = "apartment" | "house";
32
+ export type MarketListingType = "sale" | "rent";
33
+
34
+ export interface NeighborhoodSummaryQuery {
35
+ /** City name or code (`"São Paulo"`, `"sp"`). */
36
+ city: string;
37
+ neighborhood: string;
38
+ /** Echoed back; the aggregate covers every property kind today. */
39
+ propertyType?: MarketPropertyType;
40
+ /** Defaults to `"sale"`; `"rent"` answers `listing_type_unsupported`. */
41
+ type?: MarketListingType;
42
+ }
43
+
44
+ export interface NeighborhoodSummary {
45
+ available: boolean;
46
+ reason: MarketUnavailableReason | null;
47
+ /** Normalized city code (`sp` / `rj` / `bh`) when supported. */
48
+ city: string;
49
+ neighborhood: string;
50
+ propertyType: MarketPropertyType | null;
51
+ type: MarketListingType;
52
+ /** Lookback window in months. */
53
+ months: number;
54
+ /** Centavos per m². */
55
+ pricePerSqmCents: {
56
+ p25: number | null;
57
+ p50: number | null;
58
+ p75: number | null;
59
+ };
60
+ /** Pre-formatted `R$ X/m²` strings (`"—"` when missing). */
61
+ pricePerSqmFormatted: {
62
+ p25: string;
63
+ p50: string;
64
+ p75: string;
65
+ };
66
+ sampleSize: number | null;
67
+ /** pt-BR copy when unavailable. */
68
+ message: string | null;
69
+ }
70
+
71
+ /**
72
+ * Where a listing sits against the neighborhood quartiles:
73
+ * - `below_range`: under P25
74
+ * - `lower_range`: P25 ≤ price/m² < P50
75
+ * - `upper_range`: P50 ≤ price/m² ≤ P75
76
+ * - `above_range`: over P75
77
+ */
78
+ export type MarketPriceBand =
79
+ | "below_range"
80
+ | "lower_range"
81
+ | "upper_range"
82
+ | "above_range";
83
+
84
+ export interface ListingMarketPosition {
85
+ available: boolean;
86
+ reason: MarketUnavailableReason | null;
87
+ listingId: string;
88
+ city: string | null;
89
+ neighborhood: string | null;
90
+ months: number;
91
+ /** Listing asking price per m², centavos. */
92
+ listingPricePerSqmCents: number | null;
93
+ listingPricePerSqmFormatted: string;
94
+ /** Neighborhood median (P50) price per m², centavos. */
95
+ medianPricePerSqmCents: number | null;
96
+ medianPricePerSqmFormatted: string;
97
+ /** Rounded percent vs the median; negative = below the median. */
98
+ percentVsMedian: number | null;
99
+ band: MarketPriceBand | null;
100
+ sampleSize: number | null;
101
+ message: string | null;
102
+ }
103
+
104
+ export interface PriceEstimateInput {
105
+ /** City name or code (`"São Paulo"`, `"sp"`). */
106
+ city: string;
107
+ neighborhood?: string;
108
+ street?: string;
109
+ streetNumber?: string;
110
+ /** 8 digits, no dash. */
111
+ postalCode?: string;
112
+ /** m², 10–10000. */
113
+ areaSqm: number;
114
+ bedrooms?: number;
115
+ bathrooms?: number;
116
+ parkingSpots?: number;
117
+ propertyType?: MarketPropertyType;
118
+ listingType?: MarketListingType;
119
+ }
120
+
121
+ export type PriceEstimateConfidence = "high" | "medium" | "low";
122
+
123
+ export interface PriceEstimate {
124
+ available: boolean;
125
+ reason: MarketUnavailableReason | null;
126
+ city: string;
127
+ neighborhood: string | null;
128
+ estimatedPriceCents: number | null;
129
+ estimatedPriceFormatted: string;
130
+ rangeLowCents: number | null;
131
+ rangeHighCents: number | null;
132
+ rangeLowFormatted: string;
133
+ rangeHighFormatted: string;
134
+ confidenceLabel: PriceEstimateConfidence | null;
135
+ sampleSize: number | null;
136
+ /** pt-BR copy when unavailable. */
137
+ message: string | null;
138
+ }
@@ -0,0 +1,55 @@
1
+ import type { Listing } from "./types";
2
+
3
+ /**
4
+ * "Busca pelo que as fotos mostram": search a site's catalog by what the
5
+ * public photos show (`GET /api/sites/{siteId}/search/photos`).
6
+ */
7
+ export interface PhotoSearchParams {
8
+ /** Free text describing the photo ("varanda gourmet com churrasqueira"). */
9
+ q: string;
10
+ /** Listings per page (API default 12, cap 24). */
11
+ limit?: number;
12
+ /** 1-based page inside the API's candidate window. */
13
+ page?: number;
14
+ }
15
+
16
+ /** The photo that matched the words, chosen the same way as the CRM cover switch. */
17
+ export interface MatchedListingPhoto {
18
+ /** Media id; stable across listings that share the same photo. */
19
+ id: string;
20
+ src: string;
21
+ alt: string;
22
+ caption: string | null;
23
+ /**
24
+ * Vector distance for a visual match (lower is closer). `null` when the
25
+ * photo matched through its caption / room type instead (an exact text
26
+ * match, accepted as-is by {@link applyMatchedPhotoCover}).
27
+ */
28
+ distance: number | null;
29
+ }
30
+
31
+ export interface PhotoSearchItem {
32
+ /** Same card shape as `getListings` / `queryListings`. */
33
+ listing: Listing;
34
+ matchedPhoto: MatchedListingPhoto;
35
+ /** Lane score; higher is closer. Items arrive nearest-first. */
36
+ score: number;
37
+ }
38
+
39
+ export interface PhotoSearchResult {
40
+ /**
41
+ * `false` when the tenant has not enabled photo search: `items` is empty
42
+ * and the site should hide the feature rather than show "no results".
43
+ */
44
+ available: boolean;
45
+ items: PhotoSearchItem[];
46
+ /** Matching listings across every page (bounded by the API candidate window). */
47
+ total: number;
48
+ page: number;
49
+ limit: number;
50
+ }
51
+
52
+ /** A listing card whose cover was swapped for the photo that matched the search. */
53
+ export type ListingWithMatchedPhoto = Listing & {
54
+ matchedPhoto: MatchedListingPhoto | null;
55
+ };
package/src/types.ts CHANGED
@@ -284,6 +284,13 @@ export interface QueryListingsResult {
284
284
  * This is the SDK's escape hatch when `queryListings` isn't expressive
285
285
  * enough (faceted search, multi-field sort, custom grouping). It's an
286
286
  * open dictionary on purpose; the only required field is `q`.
287
+ *
288
+ * The endpoint only forwards allowlisted query / filter / sort / pagination /
289
+ * facet / grouping / highlight params. Anything that would make Typesense
290
+ * call out (`vector_query`, `nl_query`, `conversation*`, `preset`,
291
+ * `remote_embedding_*`), curation overrides (`pinned_hits`, `hidden_hits`),
292
+ * `collection`, and embedding fields in `query_by` / `include_fields` are
293
+ * dropped server-side; `per_page` is capped at 250.
287
294
  */
288
295
  export interface SearchListingsParams {
289
296
  q: string;