@garagem-ai/site-sdk 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.mts +188 -8
- package/dist/index.d.ts +188 -8
- package/dist/index.js +520 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +508 -1
- package/dist/index.mjs.map +1 -1
- package/package.json +14 -4
- package/src/applied-query.ts +42 -0
- package/src/client.ts +36 -1
- package/src/fetchers.ts +56 -2
- package/src/index.ts +35 -0
- package/src/loc-params.ts +36 -0
- package/src/path.ts +73 -0
- package/src/types.ts +107 -4
package/dist/index.d.mts
CHANGED
|
@@ -129,6 +129,122 @@ interface ListingsResult {
|
|
|
129
129
|
/** Echo of the `offset` query param actually applied. */
|
|
130
130
|
offset?: number;
|
|
131
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
|
+
}
|
|
132
248
|
/**
|
|
133
249
|
* Raw Typesense search parameters accepted by `searchListings`. Mirrors
|
|
134
250
|
* the same body the underlying `/api/sites/{siteId}/search` endpoint
|
|
@@ -136,10 +252,9 @@ interface ListingsResult {
|
|
|
136
252
|
* `per_page`, `page`, facets, etc.) — see the Typesense docs at
|
|
137
253
|
* https://typesense.org/docs/latest/api/search.html for the full list.
|
|
138
254
|
*
|
|
139
|
-
* This is the SDK's escape hatch when
|
|
140
|
-
*
|
|
141
|
-
*
|
|
142
|
-
* field is `q`.
|
|
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`.
|
|
143
258
|
*/
|
|
144
259
|
interface SearchListingsParams {
|
|
145
260
|
q: string;
|
|
@@ -275,6 +390,13 @@ interface SearchListingsOptions extends BaseOptions {
|
|
|
275
390
|
siteId: string;
|
|
276
391
|
params: SearchListingsParams;
|
|
277
392
|
}
|
|
393
|
+
interface GetSearchUiOptions extends BaseOptions {
|
|
394
|
+
siteId: string;
|
|
395
|
+
}
|
|
396
|
+
interface QueryListingsOptions extends BaseOptions {
|
|
397
|
+
siteId: string;
|
|
398
|
+
params?: QueryListingsParams;
|
|
399
|
+
}
|
|
278
400
|
interface GetSimilarListingsOptions extends BaseOptions {
|
|
279
401
|
siteId: string;
|
|
280
402
|
listingId: string;
|
|
@@ -338,8 +460,8 @@ declare function getSite(options: GetSiteOptions): Promise<Site | null>;
|
|
|
338
460
|
*
|
|
339
461
|
* Calls `POST /api/sites/{siteId}/search` directly and returns the raw
|
|
340
462
|
* Typesense response (`{ found, page, hits: [{ document, ... }], ... }`).
|
|
341
|
-
* Use when
|
|
342
|
-
*
|
|
463
|
+
* Use when `queryListings` isn't expressive enough — faceted search,
|
|
464
|
+
* multi-field sort, custom grouping, etc.
|
|
343
465
|
*
|
|
344
466
|
* @example
|
|
345
467
|
* const result = await searchListings({
|
|
@@ -359,6 +481,16 @@ declare function getSite(options: GetSiteOptions): Promise<Site | null>;
|
|
|
359
481
|
* }
|
|
360
482
|
*/
|
|
361
483
|
declare function searchListings<TDocument = Record<string, unknown>>(options: SearchListingsOptions): Promise<SearchListingsResult<TDocument>>;
|
|
484
|
+
/**
|
|
485
|
+
* Tenant search schema: filters, slugs, sort tokens, defaultLimit 12.
|
|
486
|
+
* Use this to render the search UI — do not hardcode property types.
|
|
487
|
+
*/
|
|
488
|
+
declare function getSearchUi(options: GetSearchUiOptions): Promise<SearchUi>;
|
|
489
|
+
/**
|
|
490
|
+
* Friendly catalog search (editor combinators). Prefer this over
|
|
491
|
+
* `searchListings` — that helper is a raw Typesense escape hatch.
|
|
492
|
+
*/
|
|
493
|
+
declare function queryListings(options: QueryListingsOptions): Promise<QueryListingsResult>;
|
|
362
494
|
/**
|
|
363
495
|
* Fetch similar listings for a detail page carousel.
|
|
364
496
|
* Returns an empty list when the reference listing is missing.
|
|
@@ -381,6 +513,43 @@ declare function listingPublicPath(listing: {
|
|
|
381
513
|
id?: string | null;
|
|
382
514
|
}): string;
|
|
383
515
|
|
|
516
|
+
declare function composeSearchPublicPath(filters: SearchPathFilters, dictionary?: SearchUiDictionary): string;
|
|
517
|
+
declare function parseSearchPublicPath(pathname: string, dictionary?: SearchUiDictionary): SearchPathFilters | null;
|
|
518
|
+
/**
|
|
519
|
+
* Convert `SearchPathFilters` (returned by `parseSearchPublicPath`) to
|
|
520
|
+
* `QueryListingsFilters` (accepted by `queryListings`).
|
|
521
|
+
*
|
|
522
|
+
* This maps path-based filter keys (`bedrooms`, `parkingSpots`, `area`)
|
|
523
|
+
* to the POST API keys (`property_bedrooms`, `property_parking_spots`,
|
|
524
|
+
* `property_area_total`).
|
|
525
|
+
*
|
|
526
|
+
* Location is **not** included — use `pathLocationToFilterInput` separately
|
|
527
|
+
* and pass the result as the `location` field in `QueryListingsParams`.
|
|
528
|
+
*/
|
|
529
|
+
declare function pathFiltersToQueryFilters(pathFilters: SearchPathFilters): QueryListingsFilters;
|
|
530
|
+
|
|
531
|
+
declare function parseAppliedSearchQuery(search: string | URLSearchParams): AppliedSearchQuery;
|
|
532
|
+
declare function serializeAppliedSearchQuery(query: AppliedSearchQuery): URLSearchParams;
|
|
533
|
+
declare function mergeAppliedSearchQueryIntoSearch(existing: string | URLSearchParams, query: AppliedSearchQuery): URLSearchParams;
|
|
534
|
+
declare function reduceAppliedSearchQuery(prev: AppliedSearchQuery, change: AppliedSearchChange): AppliedSearchQuery;
|
|
535
|
+
declare function composeSearchPublicHref(pathname: string, query: AppliedSearchQuery, existingSearch?: string | URLSearchParams): string;
|
|
536
|
+
|
|
537
|
+
type LocationFilterInput = {
|
|
538
|
+
type: string;
|
|
539
|
+
value: string;
|
|
540
|
+
};
|
|
541
|
+
/**
|
|
542
|
+
* Convert a SearchPathLocation (from parseSearchPublicPath) to the correct
|
|
543
|
+
* LocationFilterInput format for the friendly search API. This ensures that
|
|
544
|
+
* hierarchical location filters are ANDed correctly instead of ORed.
|
|
545
|
+
*/
|
|
546
|
+
declare function pathLocationToFilterInput(location: {
|
|
547
|
+
state?: string;
|
|
548
|
+
city?: string;
|
|
549
|
+
neighborhood?: string;
|
|
550
|
+
street?: string;
|
|
551
|
+
}): LocationFilterInput | null;
|
|
552
|
+
|
|
384
553
|
interface ResolvePublicSiteIdOptions {
|
|
385
554
|
/** Request host (`headers().get("host")`). Port is stripped. */
|
|
386
555
|
host?: string | null;
|
|
@@ -430,13 +599,24 @@ interface GaragemClient {
|
|
|
430
599
|
}): Promise<Site | null>;
|
|
431
600
|
/**
|
|
432
601
|
* Advanced search — raw Typesense parameters, raw response. Use when
|
|
433
|
-
*
|
|
602
|
+
* `queryListings` isn't expressive enough.
|
|
434
603
|
*/
|
|
435
604
|
searchListings<TDocument = Record<string, unknown>>(args: {
|
|
436
605
|
params: SearchListingsParams;
|
|
437
606
|
siteId?: string;
|
|
438
607
|
next?: RequestNextOptions;
|
|
439
608
|
}): Promise<SearchListingsResult<TDocument>>;
|
|
609
|
+
/** Tenant search schema (filters, slugs, defaultLimit). */
|
|
610
|
+
getSearchUi(args?: {
|
|
611
|
+
siteId?: string;
|
|
612
|
+
next?: RequestNextOptions;
|
|
613
|
+
}): Promise<SearchUi>;
|
|
614
|
+
/** Friendly catalog search — editor combinators, no Typesense `filter_by`. */
|
|
615
|
+
queryListings(args?: {
|
|
616
|
+
params?: QueryListingsParams;
|
|
617
|
+
siteId?: string;
|
|
618
|
+
next?: RequestNextOptions;
|
|
619
|
+
}): Promise<QueryListingsResult>;
|
|
440
620
|
/** Similar listings carousel for a detail page. */
|
|
441
621
|
getSimilarListings(args: {
|
|
442
622
|
listingId: string;
|
|
@@ -481,4 +661,4 @@ interface GaragemClient {
|
|
|
481
661
|
*/
|
|
482
662
|
declare function createGaragemClient(options?: CreateGaragemClientOptions): GaragemClient;
|
|
483
663
|
|
|
484
|
-
export { type CmsCollection, type CmsEntriesResult, type CmsEntry, type CmsEntryStatus, type CmsFieldDefinition, type CmsFieldType, type CmsSeoData, type CreateGaragemClientOptions, type FetchLike, type GaragemClient, GaragemSdkError, type GetCmsCollectionOptions, type GetCmsCollectionsOptions, type GetCmsEntriesOptions, type GetCmsEntryOptions, type GetListingOptions, type GetListingsOptions, type GetSimilarListingsOptions, type GetSiteOptions, type Listing, type ListingBusinessType, type ListingDetail, type ListingFilters, type ListingLocation, type ListingMedia, type ListingPriceVisibility, type ListingPropertySummary, type ListingsResult, type RequestNextOptions, type ResolvePublicSiteIdOptions, type SearchListingsOptions, type SearchListingsParams, type SearchListingsResult, type SimilarListingsResult, type Site, createGaragemClient, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getListing, getListings, getSimilarListings, getSite, isStudioPreviewHost, listingLookupKey, listingPublicPath, resolvePublicSiteId, searchListings };
|
|
664
|
+
export { type AppliedSearchChange, type AppliedSearchQuery, type CmsCollection, type CmsEntriesResult, type CmsEntry, type CmsEntryStatus, type CmsFieldDefinition, type CmsFieldType, type CmsSeoData, type CreateGaragemClientOptions, type FetchLike, type GaragemClient, GaragemSdkError, type GetCmsCollectionOptions, type GetCmsCollectionsOptions, type GetCmsEntriesOptions, type GetCmsEntryOptions, type GetListingOptions, type GetListingsOptions, type GetSearchUiOptions, type GetSimilarListingsOptions, type GetSiteOptions, type Listing, type ListingBusinessType, type ListingDetail, type ListingFilters, type ListingLocation, type ListingMedia, type ListingPriceVisibility, type ListingPropertySummary, type ListingsResult, type LocationFilterInput, type QueryListingsFilters, type QueryListingsLocation, type QueryListingsOptions, type QueryListingsParams, type QueryListingsResult, type RequestNextOptions, type ResolvePublicSiteIdOptions, type SearchListingsOptions, type SearchListingsParams, type SearchListingsResult, type SearchPathFilters, type SearchPathLocation, type SearchUi, type SearchUiDictionary, type SearchUiFilter, type SearchUiOption, type SimilarListingsResult, type Site, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getListing, getListings, getSearchUi, getSimilarListings, getSite, isStudioPreviewHost, listingLookupKey, listingPublicPath, mergeAppliedSearchQueryIntoSearch, parseAppliedSearchQuery, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, queryListings, reduceAppliedSearchQuery, resolvePublicSiteId, searchListings, serializeAppliedSearchQuery };
|
package/dist/index.d.ts
CHANGED
|
@@ -129,6 +129,122 @@ interface ListingsResult {
|
|
|
129
129
|
/** Echo of the `offset` query param actually applied. */
|
|
130
130
|
offset?: number;
|
|
131
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
|
+
}
|
|
132
248
|
/**
|
|
133
249
|
* Raw Typesense search parameters accepted by `searchListings`. Mirrors
|
|
134
250
|
* the same body the underlying `/api/sites/{siteId}/search` endpoint
|
|
@@ -136,10 +252,9 @@ interface ListingsResult {
|
|
|
136
252
|
* `per_page`, `page`, facets, etc.) — see the Typesense docs at
|
|
137
253
|
* https://typesense.org/docs/latest/api/search.html for the full list.
|
|
138
254
|
*
|
|
139
|
-
* This is the SDK's escape hatch when
|
|
140
|
-
*
|
|
141
|
-
*
|
|
142
|
-
* field is `q`.
|
|
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`.
|
|
143
258
|
*/
|
|
144
259
|
interface SearchListingsParams {
|
|
145
260
|
q: string;
|
|
@@ -275,6 +390,13 @@ interface SearchListingsOptions extends BaseOptions {
|
|
|
275
390
|
siteId: string;
|
|
276
391
|
params: SearchListingsParams;
|
|
277
392
|
}
|
|
393
|
+
interface GetSearchUiOptions extends BaseOptions {
|
|
394
|
+
siteId: string;
|
|
395
|
+
}
|
|
396
|
+
interface QueryListingsOptions extends BaseOptions {
|
|
397
|
+
siteId: string;
|
|
398
|
+
params?: QueryListingsParams;
|
|
399
|
+
}
|
|
278
400
|
interface GetSimilarListingsOptions extends BaseOptions {
|
|
279
401
|
siteId: string;
|
|
280
402
|
listingId: string;
|
|
@@ -338,8 +460,8 @@ declare function getSite(options: GetSiteOptions): Promise<Site | null>;
|
|
|
338
460
|
*
|
|
339
461
|
* Calls `POST /api/sites/{siteId}/search` directly and returns the raw
|
|
340
462
|
* Typesense response (`{ found, page, hits: [{ document, ... }], ... }`).
|
|
341
|
-
* Use when
|
|
342
|
-
*
|
|
463
|
+
* Use when `queryListings` isn't expressive enough — faceted search,
|
|
464
|
+
* multi-field sort, custom grouping, etc.
|
|
343
465
|
*
|
|
344
466
|
* @example
|
|
345
467
|
* const result = await searchListings({
|
|
@@ -359,6 +481,16 @@ declare function getSite(options: GetSiteOptions): Promise<Site | null>;
|
|
|
359
481
|
* }
|
|
360
482
|
*/
|
|
361
483
|
declare function searchListings<TDocument = Record<string, unknown>>(options: SearchListingsOptions): Promise<SearchListingsResult<TDocument>>;
|
|
484
|
+
/**
|
|
485
|
+
* Tenant search schema: filters, slugs, sort tokens, defaultLimit 12.
|
|
486
|
+
* Use this to render the search UI — do not hardcode property types.
|
|
487
|
+
*/
|
|
488
|
+
declare function getSearchUi(options: GetSearchUiOptions): Promise<SearchUi>;
|
|
489
|
+
/**
|
|
490
|
+
* Friendly catalog search (editor combinators). Prefer this over
|
|
491
|
+
* `searchListings` — that helper is a raw Typesense escape hatch.
|
|
492
|
+
*/
|
|
493
|
+
declare function queryListings(options: QueryListingsOptions): Promise<QueryListingsResult>;
|
|
362
494
|
/**
|
|
363
495
|
* Fetch similar listings for a detail page carousel.
|
|
364
496
|
* Returns an empty list when the reference listing is missing.
|
|
@@ -381,6 +513,43 @@ declare function listingPublicPath(listing: {
|
|
|
381
513
|
id?: string | null;
|
|
382
514
|
}): string;
|
|
383
515
|
|
|
516
|
+
declare function composeSearchPublicPath(filters: SearchPathFilters, dictionary?: SearchUiDictionary): string;
|
|
517
|
+
declare function parseSearchPublicPath(pathname: string, dictionary?: SearchUiDictionary): SearchPathFilters | null;
|
|
518
|
+
/**
|
|
519
|
+
* Convert `SearchPathFilters` (returned by `parseSearchPublicPath`) to
|
|
520
|
+
* `QueryListingsFilters` (accepted by `queryListings`).
|
|
521
|
+
*
|
|
522
|
+
* This maps path-based filter keys (`bedrooms`, `parkingSpots`, `area`)
|
|
523
|
+
* to the POST API keys (`property_bedrooms`, `property_parking_spots`,
|
|
524
|
+
* `property_area_total`).
|
|
525
|
+
*
|
|
526
|
+
* Location is **not** included — use `pathLocationToFilterInput` separately
|
|
527
|
+
* and pass the result as the `location` field in `QueryListingsParams`.
|
|
528
|
+
*/
|
|
529
|
+
declare function pathFiltersToQueryFilters(pathFilters: SearchPathFilters): QueryListingsFilters;
|
|
530
|
+
|
|
531
|
+
declare function parseAppliedSearchQuery(search: string | URLSearchParams): AppliedSearchQuery;
|
|
532
|
+
declare function serializeAppliedSearchQuery(query: AppliedSearchQuery): URLSearchParams;
|
|
533
|
+
declare function mergeAppliedSearchQueryIntoSearch(existing: string | URLSearchParams, query: AppliedSearchQuery): URLSearchParams;
|
|
534
|
+
declare function reduceAppliedSearchQuery(prev: AppliedSearchQuery, change: AppliedSearchChange): AppliedSearchQuery;
|
|
535
|
+
declare function composeSearchPublicHref(pathname: string, query: AppliedSearchQuery, existingSearch?: string | URLSearchParams): string;
|
|
536
|
+
|
|
537
|
+
type LocationFilterInput = {
|
|
538
|
+
type: string;
|
|
539
|
+
value: string;
|
|
540
|
+
};
|
|
541
|
+
/**
|
|
542
|
+
* Convert a SearchPathLocation (from parseSearchPublicPath) to the correct
|
|
543
|
+
* LocationFilterInput format for the friendly search API. This ensures that
|
|
544
|
+
* hierarchical location filters are ANDed correctly instead of ORed.
|
|
545
|
+
*/
|
|
546
|
+
declare function pathLocationToFilterInput(location: {
|
|
547
|
+
state?: string;
|
|
548
|
+
city?: string;
|
|
549
|
+
neighborhood?: string;
|
|
550
|
+
street?: string;
|
|
551
|
+
}): LocationFilterInput | null;
|
|
552
|
+
|
|
384
553
|
interface ResolvePublicSiteIdOptions {
|
|
385
554
|
/** Request host (`headers().get("host")`). Port is stripped. */
|
|
386
555
|
host?: string | null;
|
|
@@ -430,13 +599,24 @@ interface GaragemClient {
|
|
|
430
599
|
}): Promise<Site | null>;
|
|
431
600
|
/**
|
|
432
601
|
* Advanced search — raw Typesense parameters, raw response. Use when
|
|
433
|
-
*
|
|
602
|
+
* `queryListings` isn't expressive enough.
|
|
434
603
|
*/
|
|
435
604
|
searchListings<TDocument = Record<string, unknown>>(args: {
|
|
436
605
|
params: SearchListingsParams;
|
|
437
606
|
siteId?: string;
|
|
438
607
|
next?: RequestNextOptions;
|
|
439
608
|
}): Promise<SearchListingsResult<TDocument>>;
|
|
609
|
+
/** Tenant search schema (filters, slugs, defaultLimit). */
|
|
610
|
+
getSearchUi(args?: {
|
|
611
|
+
siteId?: string;
|
|
612
|
+
next?: RequestNextOptions;
|
|
613
|
+
}): Promise<SearchUi>;
|
|
614
|
+
/** Friendly catalog search — editor combinators, no Typesense `filter_by`. */
|
|
615
|
+
queryListings(args?: {
|
|
616
|
+
params?: QueryListingsParams;
|
|
617
|
+
siteId?: string;
|
|
618
|
+
next?: RequestNextOptions;
|
|
619
|
+
}): Promise<QueryListingsResult>;
|
|
440
620
|
/** Similar listings carousel for a detail page. */
|
|
441
621
|
getSimilarListings(args: {
|
|
442
622
|
listingId: string;
|
|
@@ -481,4 +661,4 @@ interface GaragemClient {
|
|
|
481
661
|
*/
|
|
482
662
|
declare function createGaragemClient(options?: CreateGaragemClientOptions): GaragemClient;
|
|
483
663
|
|
|
484
|
-
export { type CmsCollection, type CmsEntriesResult, type CmsEntry, type CmsEntryStatus, type CmsFieldDefinition, type CmsFieldType, type CmsSeoData, type CreateGaragemClientOptions, type FetchLike, type GaragemClient, GaragemSdkError, type GetCmsCollectionOptions, type GetCmsCollectionsOptions, type GetCmsEntriesOptions, type GetCmsEntryOptions, type GetListingOptions, type GetListingsOptions, type GetSimilarListingsOptions, type GetSiteOptions, type Listing, type ListingBusinessType, type ListingDetail, type ListingFilters, type ListingLocation, type ListingMedia, type ListingPriceVisibility, type ListingPropertySummary, type ListingsResult, type RequestNextOptions, type ResolvePublicSiteIdOptions, type SearchListingsOptions, type SearchListingsParams, type SearchListingsResult, type SimilarListingsResult, type Site, createGaragemClient, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getListing, getListings, getSimilarListings, getSite, isStudioPreviewHost, listingLookupKey, listingPublicPath, resolvePublicSiteId, searchListings };
|
|
664
|
+
export { type AppliedSearchChange, type AppliedSearchQuery, type CmsCollection, type CmsEntriesResult, type CmsEntry, type CmsEntryStatus, type CmsFieldDefinition, type CmsFieldType, type CmsSeoData, type CreateGaragemClientOptions, type FetchLike, type GaragemClient, GaragemSdkError, type GetCmsCollectionOptions, type GetCmsCollectionsOptions, type GetCmsEntriesOptions, type GetCmsEntryOptions, type GetListingOptions, type GetListingsOptions, type GetSearchUiOptions, type GetSimilarListingsOptions, type GetSiteOptions, type Listing, type ListingBusinessType, type ListingDetail, type ListingFilters, type ListingLocation, type ListingMedia, type ListingPriceVisibility, type ListingPropertySummary, type ListingsResult, type LocationFilterInput, type QueryListingsFilters, type QueryListingsLocation, type QueryListingsOptions, type QueryListingsParams, type QueryListingsResult, type RequestNextOptions, type ResolvePublicSiteIdOptions, type SearchListingsOptions, type SearchListingsParams, type SearchListingsResult, type SearchPathFilters, type SearchPathLocation, type SearchUi, type SearchUiDictionary, type SearchUiFilter, type SearchUiOption, type SimilarListingsResult, type Site, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getListing, getListings, getSearchUi, getSimilarListings, getSite, isStudioPreviewHost, listingLookupKey, listingPublicPath, mergeAppliedSearchQueryIntoSearch, parseAppliedSearchQuery, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, queryListings, reduceAppliedSearchQuery, resolvePublicSiteId, searchListings, serializeAppliedSearchQuery };
|