@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.
@@ -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.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
- "sideEffects": false,
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 { buildListingFiltersQuery, normalizeBaseUrl } from "./internal/url";
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 { siteId, filters, baseUrl, fetch: fetchImpl, next } = options;
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
- siteId,
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 { siteId, domain, baseUrl, fetch: fetchImpl, next } = options;
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 { siteId, params, baseUrl, fetch: fetchImpl, next } = options;
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 { siteId, baseUrl, fetch: fetchImpl, next } = options;
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 { siteId, params, baseUrl, fetch: fetchImpl, next } = options;
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 { siteId, baseUrl, fetch: fetchImpl, next } = options;
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 { siteId, slug, baseUrl, fetch: fetchImpl, next } = options;
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 { siteId, collection, slug, baseUrl, fetch: fetchImpl, next } = options;
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
  }