@garagem-ai/site-sdk 0.3.0 → 0.4.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 +26 -3
- package/dist/index.d.mts +78 -361
- package/dist/index.d.ts +78 -361
- package/dist/index.js +472 -50
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +437 -46
- package/dist/index.mjs.map +1 -1
- package/dist/listing-card-model-D7iR4asd.d.mts +402 -0
- package/dist/listing-card-model-D7iR4asd.d.ts +402 -0
- package/dist/react.d.mts +136 -0
- package/dist/react.d.ts +136 -0
- package/dist/react.js +2070 -0
- package/dist/react.js.map +1 -0
- package/dist/react.mjs +2030 -0
- package/dist/react.mjs.map +1 -0
- package/package.json +34 -1
- package/src/fetchers.ts +27 -18
- package/src/index.ts +42 -0
- package/src/internal/url.ts +14 -0
- package/src/listing-card-model.ts +90 -0
- package/src/presentation.ts +72 -0
- package/src/react/cn.ts +3 -0
- package/src/react/filter-panel.tsx +251 -0
- package/src/react/index.ts +20 -0
- package/src/react/listing-card.tsx +143 -0
- package/src/react/search-chrome.tsx +72 -0
- package/src/react/search-page.tsx +366 -0
- package/src/react/search-pagination.tsx +110 -0
- package/src/react/search-query-form.tsx +76 -0
- package/src/react/types.ts +88 -0
- package/src/react/use-public-search.ts +297 -0
- package/src/search-engine.ts +404 -0
|
@@ -0,0 +1,402 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Public types for the Garagem Sites SDK.
|
|
3
|
+
*
|
|
4
|
+
* These match the canonical shapes returned by the public Garagem
|
|
5
|
+
* Sites API (`/api/sites/...`). Treat them as the public contract —
|
|
6
|
+
* additive changes only, never breaking.
|
|
7
|
+
*/
|
|
8
|
+
/** Sale/rental indicator. The API may return additional string values; consumers should branch defensively. */
|
|
9
|
+
type ListingBusinessType = "sale" | "rental" | (string & {});
|
|
10
|
+
/** Whether the price is shown publicly or kept on request. */
|
|
11
|
+
type ListingPriceVisibility = "public" | "private";
|
|
12
|
+
/** Property-level fields shown on a listing summary card. */
|
|
13
|
+
interface ListingPropertySummary {
|
|
14
|
+
type: string;
|
|
15
|
+
bedrooms: number;
|
|
16
|
+
bathrooms: number;
|
|
17
|
+
suites: number;
|
|
18
|
+
parkingSpaces: number;
|
|
19
|
+
totalArea: number;
|
|
20
|
+
usableArea: number;
|
|
21
|
+
/** Monthly condo fee in BRL when the listing has one. */
|
|
22
|
+
condoFee?: number;
|
|
23
|
+
}
|
|
24
|
+
/** Address breakdown returned with every listing. */
|
|
25
|
+
interface ListingLocation {
|
|
26
|
+
street: string;
|
|
27
|
+
number: string;
|
|
28
|
+
complement?: string;
|
|
29
|
+
neighborhood: string;
|
|
30
|
+
city: string;
|
|
31
|
+
state: string;
|
|
32
|
+
postalCode: string;
|
|
33
|
+
country?: string;
|
|
34
|
+
coordinates?: {
|
|
35
|
+
lat: number;
|
|
36
|
+
lng: number;
|
|
37
|
+
} | null;
|
|
38
|
+
}
|
|
39
|
+
/** Single media item attached to a listing (image, video, floor plan, …). */
|
|
40
|
+
interface ListingMedia {
|
|
41
|
+
id: string;
|
|
42
|
+
type: string;
|
|
43
|
+
category: string;
|
|
44
|
+
src: string;
|
|
45
|
+
alt?: string;
|
|
46
|
+
caption?: string;
|
|
47
|
+
order?: number;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Minimum information needed to render a listing on a grid or card.
|
|
51
|
+
* Returned by `getListings`.
|
|
52
|
+
*
|
|
53
|
+
* `price` is `null` when the listing's `priceVisibility` is `"private"`
|
|
54
|
+
* (i.e. the price is hidden behind an explicit lead request) or when
|
|
55
|
+
* the underlying record has no price set. Always branch on `price ==
|
|
56
|
+
* null` rather than `!price` so genuine `0` values (rare but legal in
|
|
57
|
+
* promotional flows) don't get masked as "sob consulta".
|
|
58
|
+
*/
|
|
59
|
+
interface Listing {
|
|
60
|
+
/** Internal UUID — POST lead with this. Never put it in the URL. */
|
|
61
|
+
id: string;
|
|
62
|
+
/** Public identity for display (`#ABC`) and lookup. `null` if the row has no code. */
|
|
63
|
+
listingCode: string | null;
|
|
64
|
+
/**
|
|
65
|
+
* Canonical public href from the Sites API (`/imoveis/.../id-{listingCode}`).
|
|
66
|
+
* Prefer `listingPublicPath(listing)` so a missing `path` (CDN deploy
|
|
67
|
+
* window) still falls back to `/imoveis/id-{listingCode}`.
|
|
68
|
+
*/
|
|
69
|
+
path: string;
|
|
70
|
+
title: string;
|
|
71
|
+
description: string;
|
|
72
|
+
businessType: ListingBusinessType;
|
|
73
|
+
price: number | null;
|
|
74
|
+
priceVisibility: ListingPriceVisibility;
|
|
75
|
+
status: string;
|
|
76
|
+
featured: boolean;
|
|
77
|
+
property: ListingPropertySummary;
|
|
78
|
+
location: ListingLocation;
|
|
79
|
+
coverImage?: {
|
|
80
|
+
src: string;
|
|
81
|
+
alt: string;
|
|
82
|
+
} | null;
|
|
83
|
+
createdAt: string;
|
|
84
|
+
updatedAt: string;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Full listing data including amenities, full media gallery, building
|
|
88
|
+
* details and richer property info. Returned by `getListing`.
|
|
89
|
+
*/
|
|
90
|
+
interface ListingDetail extends Listing {
|
|
91
|
+
amenities: string[];
|
|
92
|
+
tags: string[];
|
|
93
|
+
property: ListingPropertySummary & {
|
|
94
|
+
id: string;
|
|
95
|
+
builtArea?: number;
|
|
96
|
+
landArea?: number;
|
|
97
|
+
floor?: number;
|
|
98
|
+
totalFloors?: number;
|
|
99
|
+
yearBuilt?: number;
|
|
100
|
+
furnished?: boolean;
|
|
101
|
+
petFriendly?: boolean;
|
|
102
|
+
};
|
|
103
|
+
building?: {
|
|
104
|
+
name: string;
|
|
105
|
+
amenities: string[];
|
|
106
|
+
elevators?: number;
|
|
107
|
+
unitsPerFloor?: number;
|
|
108
|
+
totalUnits?: number;
|
|
109
|
+
} | null;
|
|
110
|
+
media: ListingMedia[];
|
|
111
|
+
}
|
|
112
|
+
/** Filter / pagination options for `getListings`. */
|
|
113
|
+
interface ListingFilters {
|
|
114
|
+
limit?: number;
|
|
115
|
+
offset?: number;
|
|
116
|
+
businessType?: ListingBusinessType;
|
|
117
|
+
propertyType?: string;
|
|
118
|
+
city?: string;
|
|
119
|
+
neighborhood?: string;
|
|
120
|
+
minPrice?: number;
|
|
121
|
+
maxPrice?: number;
|
|
122
|
+
}
|
|
123
|
+
/** Wrapped response from `getListings`. */
|
|
124
|
+
interface ListingsResult {
|
|
125
|
+
listings: Listing[];
|
|
126
|
+
total: number;
|
|
127
|
+
/** Echo of the `limit` query param actually applied (subject to a 100-item cap). */
|
|
128
|
+
limit?: number;
|
|
129
|
+
/** Echo of the `offset` query param actually applied. */
|
|
130
|
+
offset?: number;
|
|
131
|
+
}
|
|
132
|
+
type SearchUiOption = {
|
|
133
|
+
id: string;
|
|
134
|
+
slug: string;
|
|
135
|
+
label: string;
|
|
136
|
+
};
|
|
137
|
+
type SearchUiFilter = {
|
|
138
|
+
id: string;
|
|
139
|
+
label: string;
|
|
140
|
+
type: "enum" | "count" | "range";
|
|
141
|
+
options?: SearchUiOption[];
|
|
142
|
+
};
|
|
143
|
+
type SearchUiDictionary = {
|
|
144
|
+
listingTypes: SearchUiOption[];
|
|
145
|
+
propertyTypes: SearchUiOption[];
|
|
146
|
+
propertyFeatures: SearchUiOption[];
|
|
147
|
+
buildingAmenities: SearchUiOption[];
|
|
148
|
+
};
|
|
149
|
+
/** Geo leftovers on a default-V2 search path (`/imoveis/...`). */
|
|
150
|
+
type SearchPathLocation = {
|
|
151
|
+
state?: string;
|
|
152
|
+
city?: string;
|
|
153
|
+
neighborhood?: string;
|
|
154
|
+
street?: string;
|
|
155
|
+
};
|
|
156
|
+
/** Filters encoded in the public search pathname (not `?loc=`). */
|
|
157
|
+
type SearchPathFilters = {
|
|
158
|
+
listingType?: ListingBusinessType | string;
|
|
159
|
+
propertyType?: string | string[];
|
|
160
|
+
location?: SearchPathLocation;
|
|
161
|
+
bedrooms?: number | number[];
|
|
162
|
+
bathrooms?: number | number[];
|
|
163
|
+
suites?: number | number[];
|
|
164
|
+
parkingSpots?: number | number[];
|
|
165
|
+
price?: {
|
|
166
|
+
min?: number;
|
|
167
|
+
max?: number;
|
|
168
|
+
};
|
|
169
|
+
area?: {
|
|
170
|
+
min?: number;
|
|
171
|
+
max?: number;
|
|
172
|
+
};
|
|
173
|
+
propertyFeatures?: string[];
|
|
174
|
+
buildingAmenities?: string[];
|
|
175
|
+
};
|
|
176
|
+
/** Query-string state on a search URL (`page`, `ordenar`, `q`, `loc`). */
|
|
177
|
+
type AppliedSearchQuery = {
|
|
178
|
+
page?: number;
|
|
179
|
+
sort?: string | null;
|
|
180
|
+
query?: string;
|
|
181
|
+
loc?: string[];
|
|
182
|
+
};
|
|
183
|
+
type AppliedSearchChange = {
|
|
184
|
+
type: "sort";
|
|
185
|
+
sort: string | null;
|
|
186
|
+
} | {
|
|
187
|
+
type: "page";
|
|
188
|
+
page: number;
|
|
189
|
+
} | {
|
|
190
|
+
type: "query";
|
|
191
|
+
query: string;
|
|
192
|
+
} | {
|
|
193
|
+
type: "loc";
|
|
194
|
+
loc: string[];
|
|
195
|
+
} | {
|
|
196
|
+
type: "applyFilters";
|
|
197
|
+
};
|
|
198
|
+
/** Tenant search schema from `GET /search-ui`. */
|
|
199
|
+
interface SearchUi {
|
|
200
|
+
defaultLimit: number;
|
|
201
|
+
maxLimit: number;
|
|
202
|
+
sorts: Array<{
|
|
203
|
+
id: string;
|
|
204
|
+
label: string;
|
|
205
|
+
}>;
|
|
206
|
+
filters: SearchUiFilter[];
|
|
207
|
+
dictionary: SearchUiDictionary;
|
|
208
|
+
locationsPath: string;
|
|
209
|
+
}
|
|
210
|
+
type QueryListingsFilters = {
|
|
211
|
+
listing_type?: string | string[];
|
|
212
|
+
property_type?: string | string[];
|
|
213
|
+
property_bedrooms?: string | string[] | number | number[];
|
|
214
|
+
property_bathrooms?: string | string[] | number | number[];
|
|
215
|
+
property_suites?: string | string[] | number | number[];
|
|
216
|
+
property_parking_spots?: string | string[] | number | number[];
|
|
217
|
+
propertyFeatures?: string[];
|
|
218
|
+
buildingAmenities?: string[];
|
|
219
|
+
price?: {
|
|
220
|
+
min?: number;
|
|
221
|
+
max?: number;
|
|
222
|
+
};
|
|
223
|
+
property_area_total?: {
|
|
224
|
+
min?: number;
|
|
225
|
+
max?: number;
|
|
226
|
+
};
|
|
227
|
+
};
|
|
228
|
+
type QueryListingsLocation = {
|
|
229
|
+
type: string;
|
|
230
|
+
value: string;
|
|
231
|
+
};
|
|
232
|
+
/** Friendly search body — Studio must not send Typesense `filter_by`. */
|
|
233
|
+
interface QueryListingsParams {
|
|
234
|
+
page?: number;
|
|
235
|
+
limit?: number;
|
|
236
|
+
sort?: string;
|
|
237
|
+
q?: string;
|
|
238
|
+
filters?: QueryListingsFilters;
|
|
239
|
+
location?: QueryListingsLocation | QueryListingsLocation[];
|
|
240
|
+
}
|
|
241
|
+
interface QueryListingsResult {
|
|
242
|
+
listings: Listing[];
|
|
243
|
+
page: number;
|
|
244
|
+
limit: number;
|
|
245
|
+
total: number;
|
|
246
|
+
totalPages: number;
|
|
247
|
+
}
|
|
248
|
+
/**
|
|
249
|
+
* Raw Typesense search parameters accepted by `searchListings`. Mirrors
|
|
250
|
+
* the same body the underlying `/api/sites/{siteId}/search` endpoint
|
|
251
|
+
* forwards to Typesense (`q`, `query_by`, `filter_by`, `sort_by`,
|
|
252
|
+
* `per_page`, `page`, facets, etc.) — see the Typesense docs at
|
|
253
|
+
* https://typesense.org/docs/latest/api/search.html for the full list.
|
|
254
|
+
*
|
|
255
|
+
* This is the SDK's escape hatch when `queryListings` isn't expressive
|
|
256
|
+
* enough (faceted search, multi-field sort, custom grouping). It's an
|
|
257
|
+
* open dictionary on purpose; the only required field is `q`.
|
|
258
|
+
*/
|
|
259
|
+
interface SearchListingsParams {
|
|
260
|
+
q: string;
|
|
261
|
+
query_by?: string;
|
|
262
|
+
filter_by?: string;
|
|
263
|
+
sort_by?: string;
|
|
264
|
+
per_page?: number;
|
|
265
|
+
page?: number;
|
|
266
|
+
facet_by?: string;
|
|
267
|
+
group_by?: string;
|
|
268
|
+
group_limit?: number;
|
|
269
|
+
/** Any other Typesense param. The SDK passes the whole object through. */
|
|
270
|
+
[key: string]: unknown;
|
|
271
|
+
}
|
|
272
|
+
/**
|
|
273
|
+
* Raw Typesense response shape — what the backend returns from
|
|
274
|
+
* `multi_search`. Generic over the document type so power users can
|
|
275
|
+
* narrow it in their own codebases without losing access to `hits[].
|
|
276
|
+
* highlight` and `text_match`.
|
|
277
|
+
*/
|
|
278
|
+
interface SearchListingsResult<TDocument = Record<string, unknown>> {
|
|
279
|
+
found: number;
|
|
280
|
+
page: number;
|
|
281
|
+
search_time_ms: number;
|
|
282
|
+
hits: Array<{
|
|
283
|
+
document: TDocument;
|
|
284
|
+
highlight?: Record<string, unknown>;
|
|
285
|
+
text_match?: number;
|
|
286
|
+
}>;
|
|
287
|
+
/** Any other Typesense field. Stays open so we don't break on engine upgrades. */
|
|
288
|
+
[key: string]: unknown;
|
|
289
|
+
}
|
|
290
|
+
/** Public summary of a Garagem-managed site. Returned by `getSite`. */
|
|
291
|
+
interface Site {
|
|
292
|
+
id: string;
|
|
293
|
+
name: string;
|
|
294
|
+
domain: string | null;
|
|
295
|
+
tenantId: string;
|
|
296
|
+
}
|
|
297
|
+
/** Wrapped response from `getSimilarListings`. */
|
|
298
|
+
interface SimilarListingsResult {
|
|
299
|
+
listings: Listing[];
|
|
300
|
+
total: number;
|
|
301
|
+
}
|
|
302
|
+
/** CMS field type mirrored from the public CMS worker. */
|
|
303
|
+
type CmsFieldType = "text" | "richText" | "image" | "date" | "select" | "number" | "url" | "entry-reference";
|
|
304
|
+
interface CmsFieldDefinition {
|
|
305
|
+
id: string;
|
|
306
|
+
label: string;
|
|
307
|
+
type: CmsFieldType;
|
|
308
|
+
required?: boolean;
|
|
309
|
+
placeholder?: string;
|
|
310
|
+
options?: string[];
|
|
311
|
+
targetCollection?: string;
|
|
312
|
+
displayField?: string;
|
|
313
|
+
inheritFields?: string[];
|
|
314
|
+
inheritLevelField?: boolean;
|
|
315
|
+
}
|
|
316
|
+
/** CMS collection schema. Returned by `getCmsCollections` / `getCmsCollection`. */
|
|
317
|
+
interface CmsCollection {
|
|
318
|
+
id: string;
|
|
319
|
+
name: string;
|
|
320
|
+
slug: string;
|
|
321
|
+
templatePageId: string | null;
|
|
322
|
+
fields: CmsFieldDefinition[];
|
|
323
|
+
createdAt: string;
|
|
324
|
+
updatedAt: string;
|
|
325
|
+
}
|
|
326
|
+
type CmsEntryStatus = "draft" | "ready" | "published";
|
|
327
|
+
interface CmsSeoData {
|
|
328
|
+
title?: string;
|
|
329
|
+
description?: string;
|
|
330
|
+
ogImage?: string;
|
|
331
|
+
}
|
|
332
|
+
/** Published CMS entry. Returned by `getCmsEntries` / `getCmsEntry`. */
|
|
333
|
+
interface CmsEntry {
|
|
334
|
+
id: string;
|
|
335
|
+
collectionId: string;
|
|
336
|
+
slug: string;
|
|
337
|
+
status: CmsEntryStatus;
|
|
338
|
+
fields: Record<string, unknown>;
|
|
339
|
+
seo: CmsSeoData | null;
|
|
340
|
+
publishedAt: string | null;
|
|
341
|
+
createdAt: string;
|
|
342
|
+
updatedAt: string;
|
|
343
|
+
}
|
|
344
|
+
interface CmsEntriesResult {
|
|
345
|
+
entries: CmsEntry[];
|
|
346
|
+
total: number;
|
|
347
|
+
limit: number;
|
|
348
|
+
offset: number;
|
|
349
|
+
}
|
|
350
|
+
/**
|
|
351
|
+
* App Router caching hints passed straight through to the underlying
|
|
352
|
+
* `fetch` call. See https://nextjs.org/docs/app/api-reference/functions/fetch.
|
|
353
|
+
*
|
|
354
|
+
* Typed loosely so this works in plain Node, Edge, Cloudflare Workers
|
|
355
|
+
* and Bun runtimes without Next-specific types being mandatory.
|
|
356
|
+
*/
|
|
357
|
+
interface RequestNextOptions {
|
|
358
|
+
revalidate?: number | false;
|
|
359
|
+
tags?: string[];
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
/** Fields every listing card must have — no JSX. */
|
|
363
|
+
type ListingCardModel = {
|
|
364
|
+
href: string;
|
|
365
|
+
title: string;
|
|
366
|
+
businessType: ListingBusinessType;
|
|
367
|
+
businessLabel: string;
|
|
368
|
+
priceVisibility: ListingPriceVisibility;
|
|
369
|
+
price: number | null;
|
|
370
|
+
priceLabel: string;
|
|
371
|
+
pricePeriod: string | null;
|
|
372
|
+
locationLabel: string;
|
|
373
|
+
propertyType: string | null;
|
|
374
|
+
coverSrc: string | null;
|
|
375
|
+
coverAlt: string;
|
|
376
|
+
bedrooms: number | null;
|
|
377
|
+
bathrooms: number | null;
|
|
378
|
+
parkingSpaces: number | null;
|
|
379
|
+
areaM2: number | null;
|
|
380
|
+
};
|
|
381
|
+
declare function listingLocationLabel(location: {
|
|
382
|
+
neighborhood?: string | null;
|
|
383
|
+
city?: string | null;
|
|
384
|
+
state?: string | null;
|
|
385
|
+
}): string;
|
|
386
|
+
declare function toListingCardModel(listing: Pick<Listing, "id" | "listingCode" | "path" | "title" | "businessType" | "price" | "priceVisibility" | "coverImage"> & {
|
|
387
|
+
property?: {
|
|
388
|
+
type?: string | null;
|
|
389
|
+
bedrooms?: number | null;
|
|
390
|
+
bathrooms?: number | null;
|
|
391
|
+
parkingSpaces?: number | null;
|
|
392
|
+
usableArea?: number | null;
|
|
393
|
+
totalArea?: number | null;
|
|
394
|
+
};
|
|
395
|
+
location?: {
|
|
396
|
+
neighborhood?: string | null;
|
|
397
|
+
city?: string | null;
|
|
398
|
+
state?: string | null;
|
|
399
|
+
};
|
|
400
|
+
}): ListingCardModel;
|
|
401
|
+
|
|
402
|
+
export { type AppliedSearchQuery as A, type QueryListingsLocation as B, type CmsCollection as C, type SearchPathLocation as D, listingLocationLabel as E, toListingCardModel as F, type ListingFilters as L, type QueryListingsParams as Q, type RequestNextOptions as R, type SearchListingsParams as S, type CmsEntriesResult as a, type CmsEntry as b, type ListingDetail as c, type ListingsResult as d, type SearchUi as e, type SimilarListingsResult as f, type Site as g, type QueryListingsResult as h, type SearchListingsResult as i, type SearchPathFilters as j, type SearchUiDictionary as k, type SearchUiOption as l, type AppliedSearchChange as m, type SearchUiFilter as n, type QueryListingsFilters as o, type CmsEntryStatus as p, type CmsFieldDefinition as q, type CmsFieldType as r, type CmsSeoData as s, type Listing as t, type ListingBusinessType as u, type ListingCardModel as v, type ListingLocation as w, type ListingMedia as x, type ListingPriceVisibility as y, type ListingPropertySummary as z };
|