@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 };