@garagem-ai/site-sdk 0.3.0 → 0.4.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/README.md +59 -3
- package/dist/index.d.mts +27 -361
- package/dist/index.d.ts +27 -361
- package/dist/index.js +530 -50
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +493 -46
- package/dist/index.mjs.map +1 -1
- package/dist/react.d.mts +163 -0
- package/dist/react.d.ts +163 -0
- package/dist/react.js +2124 -0
- package/dist/react.js.map +1 -0
- package/dist/react.mjs +2083 -0
- package/dist/react.mjs.map +1 -0
- package/dist/search-engine-D4EZkNrQ.d.mts +468 -0
- package/dist/search-engine-D4EZkNrQ.d.ts +468 -0
- package/package.json +42 -4
- package/src/fetchers.ts +27 -18
- package/src/index.ts +44 -0
- package/src/internal/url.ts +14 -0
- package/src/listing-card-model.ts +90 -0
- package/src/presentation.ts +79 -0
- package/src/react/cn.ts +3 -0
- package/src/react/filter-panel.tsx +248 -0
- package/src/react/icons.tsx +46 -0
- package/src/react/index.ts +26 -0
- package/src/react/listing-card.tsx +86 -0
- package/src/react/search-chrome.tsx +73 -0
- package/src/react/search-page.tsx +465 -0
- package/src/react/search-pagination.tsx +120 -0
- package/src/react/search-query-form.tsx +81 -0
- package/src/react/search.css +717 -0
- package/src/react/styles/index.ts +1 -0
- package/src/react/styles/search-chrome-css.generated.ts +5 -0
- package/src/react/styles/search-chrome-styles.tsx +12 -0
- package/src/react/types.ts +106 -0
- package/src/react/use-public-search.ts +304 -0
- package/src/search-engine.ts +483 -0
|
@@ -0,0 +1,468 @@
|
|
|
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
|
+
/** Query keys that must never encode filters (Editor/Studio path contract). */
|
|
403
|
+
declare const FORBIDDEN_SEARCH_QUERY_KEYS: readonly ["tipo", "quartos", "tipo-imovel", "banheiros", "vagas"];
|
|
404
|
+
/** Default option: omit `ordenar` (API has no relevance token). */
|
|
405
|
+
declare const SEARCH_SORT_RELEVANCE: {
|
|
406
|
+
readonly id: "";
|
|
407
|
+
readonly label: "Mais relevantes";
|
|
408
|
+
};
|
|
409
|
+
declare function searchSortOptions(sorts: Array<{
|
|
410
|
+
id: string;
|
|
411
|
+
label: string;
|
|
412
|
+
}> | undefined): Array<{
|
|
413
|
+
id: string;
|
|
414
|
+
label: string;
|
|
415
|
+
}>;
|
|
416
|
+
/** Toolbar: price + bedrooms first and required when the schema has them. */
|
|
417
|
+
declare const TOOLBAR_PRIMARY_FILTER_IDS: readonly ["price", "property_bedrooms"];
|
|
418
|
+
declare function isListingDetailPath(pathname: string): boolean;
|
|
419
|
+
declare function readPublicSearch(pathname: string, search: string, dictionary?: SearchUiDictionary): {
|
|
420
|
+
pathFilters: SearchPathFilters;
|
|
421
|
+
applied: AppliedSearchQuery;
|
|
422
|
+
};
|
|
423
|
+
type LocationNameTables = {
|
|
424
|
+
states?: Record<string, string>;
|
|
425
|
+
cities?: Record<string, string>;
|
|
426
|
+
neighborhoods?: Record<string, string>;
|
|
427
|
+
streets?: Record<string, string>;
|
|
428
|
+
};
|
|
429
|
+
declare function displayPathLocation(location: SearchPathFilters["location"], values?: LocationNameTables | null): SearchPathFilters["location"] | null;
|
|
430
|
+
declare function buildQueryListingsParams(pathFilters: SearchPathFilters, applied: AppliedSearchQuery, schema: Pick<SearchUi, "defaultLimit"> | {
|
|
431
|
+
defaultLimit?: number;
|
|
432
|
+
} | null, locationValues?: LocationNameTables | null): QueryListingsParams;
|
|
433
|
+
declare function applyPathFilter(pathFilters: SearchPathFilters, filterId: string, value: unknown): SearchPathFilters;
|
|
434
|
+
declare function pathFilterValue(pathFilters: SearchPathFilters | undefined, filterId: string): string;
|
|
435
|
+
declare function pathFilterHasOption(pathFilters: SearchPathFilters | undefined, filterId: string, optionId: string): boolean;
|
|
436
|
+
declare function publicSearchHref(pathFilters: SearchPathFilters, applied: AppliedSearchQuery, dictionary?: SearchUiDictionary, existingSearch?: string): string;
|
|
437
|
+
declare function hrefForPathFilters(pathname: string, search: string, dictionary: SearchUiDictionary | undefined, nextPathFilters: SearchPathFilters): string;
|
|
438
|
+
declare function hrefForAppliedChange(pathname: string, search: string, dictionary: SearchUiDictionary | undefined, change: AppliedSearchChange): string;
|
|
439
|
+
/** Canonical href if the current URL is out of generation order; otherwise null. */
|
|
440
|
+
declare function canonicalizeSearchHref(pathname: string, search: string, dictionary?: SearchUiDictionary): string | null;
|
|
441
|
+
declare function searchHrefUsesLegacyFilterQuery(href: string): boolean;
|
|
442
|
+
/**
|
|
443
|
+
* Drop staged filters. Location always stays until apply.
|
|
444
|
+
* `keepFilterIds` keeps toolbar-primary filters (price, bedrooms) so Limpar
|
|
445
|
+
* in the extra-filters dialog does not wipe values already on the toolbar.
|
|
446
|
+
*/
|
|
447
|
+
declare function clearStagedPathFilters(current: SearchPathFilters, keepFilterIds?: readonly string[]): SearchPathFilters;
|
|
448
|
+
declare function visibleSearchFilters(schema: SearchUi | null): SearchUiFilter[];
|
|
449
|
+
declare function toolbarFilterIds(schema: SearchUi | null): string[];
|
|
450
|
+
declare function countOptionLabel(option: Pick<SearchUiOption, "label">): string;
|
|
451
|
+
declare function countFacetChoices(options: SearchUiOption[] | undefined): Array<{
|
|
452
|
+
id: string;
|
|
453
|
+
label: string;
|
|
454
|
+
}>;
|
|
455
|
+
/**
|
|
456
|
+
* SEO H1 for a search URL. Must stay stable for the same path — never
|
|
457
|
+
* include the hit count (Google treats a changing H1 on one URL as
|
|
458
|
+
* volatile). Count is rendered in a sibling `<span>`.
|
|
459
|
+
*/
|
|
460
|
+
declare function searchResultsHeading(pathFilters: SearchPathFilters, dictionary?: SearchUiDictionary | null, locationNames?: LocationNameTables | null): string;
|
|
461
|
+
/**
|
|
462
|
+
* Next App Router does not navigate when the href is unchanged. Canonical
|
|
463
|
+
* URLs omit `page=1`, so pagination must still emit `?page=1` on the link.
|
|
464
|
+
*/
|
|
465
|
+
declare function hrefWithExplicitPage(href: string, page: number): string;
|
|
466
|
+
declare function paginationPages(currentPage: number, totalPages: number, padding: number): number[];
|
|
467
|
+
|
|
468
|
+
export { publicSearchHref as $, type AppliedSearchQuery as A, SEARCH_SORT_RELEVANCE as B, type CmsCollection as C, type SearchPathLocation as D, type SearchUiFilter as E, FORBIDDEN_SEARCH_QUERY_KEYS as F, type SearchUiOption as G, applyPathFilter as H, buildQueryListingsParams as I, canonicalizeSearchHref as J, clearStagedPathFilters as K, type ListingFilters as L, countFacetChoices as M, countOptionLabel as N, displayPathLocation as O, hrefForAppliedChange as P, type QueryListingsParams as Q, type RequestNextOptions as R, type SearchListingsParams as S, TOOLBAR_PRIMARY_FILTER_IDS as T, hrefForPathFilters as U, hrefWithExplicitPage as V, isListingDetailPath as W, listingLocationLabel as X, paginationPages as Y, pathFilterHasOption as Z, pathFilterValue as _, type CmsEntriesResult as a, readPublicSearch as a0, searchHrefUsesLegacyFilterQuery as a1, searchResultsHeading as a2, searchSortOptions as a3, toListingCardModel as a4, toolbarFilterIds as a5, visibleSearchFilters as a6, 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 QueryListingsFilters as l, type AppliedSearchChange as m, type CmsEntryStatus as n, type CmsFieldDefinition as o, type CmsFieldType as p, type CmsSeoData as q, type Listing as r, type ListingBusinessType as s, type ListingCardModel as t, type ListingLocation as u, type ListingMedia as v, type ListingPriceVisibility as w, type ListingPropertySummary as x, type LocationNameTables as y, type QueryListingsLocation 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.4.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",
|
|
@@ -12,7 +12,14 @@
|
|
|
12
12
|
"import": "./dist/index.mjs",
|
|
13
13
|
"require": "./dist/index.js",
|
|
14
14
|
"default": "./dist/index.js"
|
|
15
|
-
}
|
|
15
|
+
},
|
|
16
|
+
"./react": {
|
|
17
|
+
"types": "./dist/react.d.ts",
|
|
18
|
+
"import": "./dist/react.mjs",
|
|
19
|
+
"require": "./dist/react.js",
|
|
20
|
+
"default": "./dist/react.js"
|
|
21
|
+
},
|
|
22
|
+
"./react/search.css": "./src/react/search.css"
|
|
16
23
|
},
|
|
17
24
|
"files": [
|
|
18
25
|
"dist",
|
|
@@ -28,10 +35,18 @@
|
|
|
28
35
|
"import": "./dist/index.mjs",
|
|
29
36
|
"require": "./dist/index.js",
|
|
30
37
|
"default": "./dist/index.js"
|
|
31
|
-
}
|
|
38
|
+
},
|
|
39
|
+
"./react": {
|
|
40
|
+
"types": "./dist/react.d.ts",
|
|
41
|
+
"import": "./dist/react.mjs",
|
|
42
|
+
"require": "./dist/react.js",
|
|
43
|
+
"default": "./dist/react.js"
|
|
44
|
+
},
|
|
45
|
+
"./react/search.css": "./src/react/search.css"
|
|
32
46
|
}
|
|
33
47
|
},
|
|
34
48
|
"scripts": {
|
|
49
|
+
"prebuild": "node scripts/build-search-chrome-css.mjs",
|
|
35
50
|
"build": "tsup",
|
|
36
51
|
"dev": "tsup --watch",
|
|
37
52
|
"test": "vitest run",
|
|
@@ -41,13 +56,36 @@
|
|
|
41
56
|
},
|
|
42
57
|
"devDependencies": {
|
|
43
58
|
"@garagem/search-url": "workspace:*",
|
|
59
|
+
"@types/node": "^20.10.8",
|
|
60
|
+
"@types/react": "19.1.4",
|
|
61
|
+
"next": "16.3.0",
|
|
62
|
+
"react": "19.2.1",
|
|
63
|
+
"react-dom": "19.2.1",
|
|
44
64
|
"tsup": "^8.0.1",
|
|
45
65
|
"typescript": "^5.3.3",
|
|
46
66
|
"vitest": "^4.0.0",
|
|
47
67
|
"@garagem/eslint-config": "workspace:*",
|
|
48
68
|
"eslint": "^9.0.0"
|
|
49
69
|
},
|
|
50
|
-
"
|
|
70
|
+
"peerDependencies": {
|
|
71
|
+
"next": ">=14",
|
|
72
|
+
"react": ">=18",
|
|
73
|
+
"react-dom": ">=18"
|
|
74
|
+
},
|
|
75
|
+
"peerDependenciesMeta": {
|
|
76
|
+
"next": {
|
|
77
|
+
"optional": true
|
|
78
|
+
},
|
|
79
|
+
"react": {
|
|
80
|
+
"optional": true
|
|
81
|
+
},
|
|
82
|
+
"react-dom": {
|
|
83
|
+
"optional": true
|
|
84
|
+
}
|
|
85
|
+
},
|
|
86
|
+
"sideEffects": [
|
|
87
|
+
"**/*.css"
|
|
88
|
+
],
|
|
51
89
|
"keywords": [
|
|
52
90
|
"garagem",
|
|
53
91
|
"real-estate",
|
package/src/fetchers.ts
CHANGED
|
@@ -16,7 +16,11 @@ import type {
|
|
|
16
16
|
Site,
|
|
17
17
|
} from "./types";
|
|
18
18
|
import { listingLookupKey } from "./listing-path";
|
|
19
|
-
import {
|
|
19
|
+
import {
|
|
20
|
+
buildListingFiltersQuery,
|
|
21
|
+
coerceSiteId,
|
|
22
|
+
normalizeBaseUrl,
|
|
23
|
+
} from "./internal/url";
|
|
20
24
|
|
|
21
25
|
/** Custom fetch implementation. Defaults to the global `fetch`. */
|
|
22
26
|
export type FetchLike = typeof fetch;
|
|
@@ -144,7 +148,8 @@ export class GaragemSdkError extends Error {
|
|
|
144
148
|
export async function getListings(
|
|
145
149
|
options: GetListingsOptions
|
|
146
150
|
): Promise<ListingsResult> {
|
|
147
|
-
const {
|
|
151
|
+
const { filters, baseUrl, fetch: fetchImpl, next } = options;
|
|
152
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
148
153
|
const base = normalizeBaseUrl(baseUrl);
|
|
149
154
|
const params = buildListingFiltersQuery(filters);
|
|
150
155
|
const qs = params.size > 0 ? `?${params.toString()}` : "";
|
|
@@ -168,13 +173,8 @@ export async function getListings(
|
|
|
168
173
|
export async function getListing(
|
|
169
174
|
options: GetListingOptions
|
|
170
175
|
): Promise<ListingDetail> {
|
|
171
|
-
const {
|
|
172
|
-
|
|
173
|
-
listingId: rawListingId,
|
|
174
|
-
baseUrl,
|
|
175
|
-
fetch: fetchImpl,
|
|
176
|
-
next,
|
|
177
|
-
} = options;
|
|
176
|
+
const { listingId: rawListingId, baseUrl, fetch: fetchImpl, next } = options;
|
|
177
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
178
178
|
const listingId = listingLookupKey(rawListingId ?? "");
|
|
179
179
|
if (!listingId || listingId === "undefined" || listingId === "null") {
|
|
180
180
|
throw new TypeError("getListing: `listingId` is required");
|
|
@@ -200,7 +200,10 @@ export async function getListing(
|
|
|
200
200
|
* if (!site) return notFound();
|
|
201
201
|
*/
|
|
202
202
|
export async function getSite(options: GetSiteOptions): Promise<Site | null> {
|
|
203
|
-
const {
|
|
203
|
+
const { domain, baseUrl, fetch: fetchImpl, next } = options;
|
|
204
|
+
const siteId = options.siteId
|
|
205
|
+
? await coerceSiteId(options.siteId)
|
|
206
|
+
: undefined;
|
|
204
207
|
if (!siteId && !domain) {
|
|
205
208
|
throw new TypeError(
|
|
206
209
|
"getSite: provide exactly one of `siteId` or `domain`."
|
|
@@ -273,7 +276,8 @@ export async function getSite(options: GetSiteOptions): Promise<Site | null> {
|
|
|
273
276
|
export async function searchListings<TDocument = Record<string, unknown>>(
|
|
274
277
|
options: SearchListingsOptions
|
|
275
278
|
): Promise<SearchListingsResult<TDocument>> {
|
|
276
|
-
const {
|
|
279
|
+
const { params, baseUrl, fetch: fetchImpl, next } = options;
|
|
280
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
277
281
|
if (!params || typeof params.q !== "string") {
|
|
278
282
|
throw new TypeError(
|
|
279
283
|
"Garagem SDK: searchListings requires `params.q` (Typesense query string)."
|
|
@@ -300,7 +304,8 @@ export async function searchListings<TDocument = Record<string, unknown>>(
|
|
|
300
304
|
export async function getSearchUi(
|
|
301
305
|
options: GetSearchUiOptions
|
|
302
306
|
): Promise<SearchUi> {
|
|
303
|
-
const {
|
|
307
|
+
const { baseUrl, fetch: fetchImpl, next } = options;
|
|
308
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
304
309
|
const base = normalizeBaseUrl(baseUrl);
|
|
305
310
|
const url = `${base}/api/sites/${encodeURIComponent(siteId)}/search-ui`;
|
|
306
311
|
return callJson<SearchUi>(
|
|
@@ -317,7 +322,8 @@ export async function getSearchUi(
|
|
|
317
322
|
export async function queryListings(
|
|
318
323
|
options: QueryListingsOptions
|
|
319
324
|
): Promise<QueryListingsResult> {
|
|
320
|
-
const {
|
|
325
|
+
const { params, baseUrl, fetch: fetchImpl, next } = options;
|
|
326
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
321
327
|
const base = normalizeBaseUrl(baseUrl);
|
|
322
328
|
const url = `${base}/api/sites/${encodeURIComponent(siteId)}/search/listings`;
|
|
323
329
|
return callJson<QueryListingsResult>(
|
|
@@ -343,13 +349,13 @@ export async function getSimilarListings(
|
|
|
343
349
|
options: GetSimilarListingsOptions
|
|
344
350
|
): Promise<SimilarListingsResult> {
|
|
345
351
|
const {
|
|
346
|
-
siteId,
|
|
347
352
|
listingId: rawListingId,
|
|
348
353
|
limit,
|
|
349
354
|
baseUrl,
|
|
350
355
|
fetch: fetchImpl,
|
|
351
356
|
next,
|
|
352
357
|
} = options;
|
|
358
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
353
359
|
const listingId = listingLookupKey(rawListingId ?? "");
|
|
354
360
|
if (!listingId || listingId === "undefined" || listingId === "null") {
|
|
355
361
|
throw new TypeError("getSimilarListings: `listingId` is required");
|
|
@@ -379,7 +385,8 @@ export async function getSimilarListings(
|
|
|
379
385
|
export async function getCmsCollections(
|
|
380
386
|
options: GetCmsCollectionsOptions
|
|
381
387
|
): Promise<CmsCollection[]> {
|
|
382
|
-
const {
|
|
388
|
+
const { baseUrl, fetch: fetchImpl, next } = options;
|
|
389
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
383
390
|
const base = normalizeBaseUrl(baseUrl);
|
|
384
391
|
const url = `${base}/api/sites/${encodeURIComponent(siteId)}/cms/collections`;
|
|
385
392
|
const data = await callJson<{ collections?: CmsCollection[] }>(
|
|
@@ -394,7 +401,8 @@ export async function getCmsCollections(
|
|
|
394
401
|
export async function getCmsCollection(
|
|
395
402
|
options: GetCmsCollectionOptions
|
|
396
403
|
): Promise<CmsCollection> {
|
|
397
|
-
const {
|
|
404
|
+
const { slug, baseUrl, fetch: fetchImpl, next } = options;
|
|
405
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
398
406
|
if (!slug) {
|
|
399
407
|
throw new TypeError("getCmsCollection: `slug` is required");
|
|
400
408
|
}
|
|
@@ -423,7 +431,6 @@ export async function getCmsEntries(
|
|
|
423
431
|
options: GetCmsEntriesOptions
|
|
424
432
|
): Promise<CmsEntriesResult> {
|
|
425
433
|
const {
|
|
426
|
-
siteId,
|
|
427
434
|
collection,
|
|
428
435
|
limit,
|
|
429
436
|
offset,
|
|
@@ -431,6 +438,7 @@ export async function getCmsEntries(
|
|
|
431
438
|
fetch: fetchImpl,
|
|
432
439
|
next,
|
|
433
440
|
} = options;
|
|
441
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
434
442
|
if (!collection) {
|
|
435
443
|
throw new TypeError("getCmsEntries: `collection` is required");
|
|
436
444
|
}
|
|
@@ -464,7 +472,8 @@ export async function getCmsEntries(
|
|
|
464
472
|
export async function getCmsEntry(
|
|
465
473
|
options: GetCmsEntryOptions
|
|
466
474
|
): Promise<CmsEntry> {
|
|
467
|
-
const {
|
|
475
|
+
const { collection, slug, baseUrl, fetch: fetchImpl, next } = options;
|
|
476
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
468
477
|
if (!collection) {
|
|
469
478
|
throw new TypeError("getCmsEntry: `collection` is required");
|
|
470
479
|
}
|