@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 CHANGED
@@ -241,11 +241,67 @@ add **publishable keys** with per-tenant rate limits and a domain allowlist —
241
241
  no breaking changes to the call sites, just an additional `publishableKey`
242
242
  option on `createGaragemClient`.
243
243
 
244
- ## What's NOT in v0.2
244
+ ## Search UI (`@garagem-ai/site-sdk/react`)
245
+
246
+ Headless URL/search helpers live on the main entry (`readPublicSearch`,
247
+ `hrefForPathFilters`, `toListingCardModel`, …). The React adapter is a
248
+ separate subpath — peer `react` + `next`:
249
+
250
+ ```tsx
251
+ import { SearchChromeStyles } from "@garagem-ai/site-sdk/react";
252
+
253
+ export default function RootLayout({
254
+ children,
255
+ }: {
256
+ children: React.ReactNode;
257
+ }) {
258
+ return (
259
+ <html lang="pt-BR">
260
+ <body>
261
+ <SearchChromeStyles />
262
+ {children}
263
+ </body>
264
+ </html>
265
+ );
266
+ }
267
+ ```
268
+
269
+ ```tsx
270
+ "use client";
271
+ import { Suspense } from "react";
272
+ import { SearchPage, SearchPageFallback } from "@garagem-ai/site-sdk/react";
273
+
274
+ export default function ImoveisPage() {
275
+ return (
276
+ <Suspense fallback={<SearchPageFallback />}>
277
+ <SearchPage
278
+ siteId={process.env.NEXT_PUBLIC_GARAGEM_SITE_ID!}
279
+ variant="toolbar"
280
+ />
281
+ </Suspense>
282
+ );
283
+ }
284
+ ```
285
+
286
+ `variant` is `toolbar` (default), `dialog`, or `sidebar`. Studio and v0
287
+ preview must use `SearchChromeStyles` (a JS module that emits a `<style>`
288
+ tag). Do not `import "@garagem-ai/site-sdk/react/search.css"` in generated
289
+ Studio apps — the preview ESM CDN cannot load npm CSS. That file export
290
+ remains for plain Next consumers who prefer a CSS import.
291
+
292
+ `SearchPage` and `SearchPageFallback` also emit the sheet if the layout
293
+ omits `SearchChromeStyles`. Home listing cards still need the layout tag
294
+ (or a parent that renders it). Customize with CSS variables
295
+ (`SEARCH_CSS_VARS` / `SEARCH_CSS_RECIPE` in `globals.css`), `classNames`,
296
+ `icons`, and `data-slot`. Home and search should share `ListingCard`.
297
+ The search H1 is SEO stable: hit count is a sibling `<span>`, not inside
298
+ `<h1>`. Presentation tokens stay framework-free on the main entry so
299
+ other adapters can reuse them.
300
+
301
+ ## What's NOT in this release
245
302
 
246
303
  - CMS writes / drafts (editor + CMS worker only).
247
- - Typesense / InstantSearch helpers — coming as separate `@garagem-ai/site-sdk/search` subpath.
248
- - React hooks (`useListings`, `useSearch`, …) — coming as `@garagem-ai/site-sdk/react` subpath.
304
+ - Typesense / InstantSearch helpers.
249
305
  - LiveSession / lead submission helpers.
250
306
 
251
307
  All of these will land additively; the v0.2 surface above will not break.
package/dist/index.d.mts CHANGED
@@ -1,363 +1,5 @@
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
- }
1
+ import { R as RequestNextOptions, L as ListingFilters, Q as QueryListingsParams, S as SearchListingsParams, C as CmsCollection, a as CmsEntriesResult, b as CmsEntry, c as ListingDetail, d as ListingsResult, e as SearchUi, f as SimilarListingsResult, g as Site, h as QueryListingsResult, i as SearchListingsResult, j as SearchPathFilters, k as SearchUiDictionary, l as QueryListingsFilters, A as AppliedSearchQuery, m as AppliedSearchChange } from './search-engine-D4EZkNrQ.mjs';
2
+ export { n as CmsEntryStatus, o as CmsFieldDefinition, p as CmsFieldType, q as CmsSeoData, F as FORBIDDEN_SEARCH_QUERY_KEYS, r as Listing, s as ListingBusinessType, t as ListingCardModel, u as ListingLocation, v as ListingMedia, w as ListingPriceVisibility, x as ListingPropertySummary, y as LocationNameTables, z as QueryListingsLocation, B as SEARCH_SORT_RELEVANCE, D as SearchPathLocation, E as SearchUiFilter, G as SearchUiOption, T as TOOLBAR_PRIMARY_FILTER_IDS, H as applyPathFilter, I as buildQueryListingsParams, J as canonicalizeSearchHref, K as clearStagedPathFilters, M as countFacetChoices, N as countOptionLabel, O as displayPathLocation, P as hrefForAppliedChange, U as hrefForPathFilters, V as hrefWithExplicitPage, W as isListingDetailPath, X as listingLocationLabel, Y as paginationPages, Z as pathFilterHasOption, _ as pathFilterValue, $ as publicSearchHref, a0 as readPublicSearch, a1 as searchHrefUsesLegacyFilterQuery, a2 as searchResultsHeading, a3 as searchSortOptions, a4 as toListingCardModel, a5 as toolbarFilterIds, a6 as visibleSearchFilters } from './search-engine-D4EZkNrQ.mjs';
361
3
 
362
4
  /** Custom fetch implementation. Defaults to the global `fetch`. */
363
5
  type FetchLike = typeof fetch;
@@ -513,6 +155,30 @@ declare function listingPublicPath(listing: {
513
155
  id?: string | null;
514
156
  }): string;
515
157
 
158
+ /**
159
+ * Presentation helpers with no UI framework.
160
+ * React / React Native / Flutter adapters consume these formatters and
161
+ * CSS custom-property names; they must not live inside JSX.
162
+ */
163
+ declare const SEARCH_CSS_VARS: {
164
+ readonly cardRadius: "--garagem-listing-card-radius";
165
+ readonly cardGap: "--garagem-listing-card-gap";
166
+ readonly priceSize: "--garagem-listing-price-size";
167
+ readonly mediaRatio: "--garagem-listing-media-ratio";
168
+ readonly controlHeight: "--garagem-search-control-height";
169
+ readonly iconSize: "--garagem-search-icon-size";
170
+ readonly skeleton: "--garagem-skeleton";
171
+ };
172
+ /** Paste into generated `globals.css` to override tokens. Layout lives in the chrome artifact. */
173
+ declare const SEARCH_CSS_RECIPE: string;
174
+ declare function formatListingPrice(amount: number | null | undefined, locale?: string, currency?: string): string;
175
+ /** Input mask: `499000` → `"499.000"` (no currency symbol). */
176
+ declare function formatGroupedInteger(value: string | number | null | undefined, locale?: string): string;
177
+ /** Inverse of `formatGroupedInteger`: `"499.000"` / `"499000"` → `499000`. */
178
+ declare function parseGroupedInteger(value: unknown): number | undefined;
179
+ declare function formatAreaM2(area: number | null | undefined): string | null;
180
+ declare function listingBusinessLabel(businessType: string | undefined): string;
181
+
516
182
  declare function composeSearchPublicPath(filters: SearchPathFilters, dictionary?: SearchUiDictionary): string;
517
183
  declare function parseSearchPublicPath(pathname: string, dictionary?: SearchUiDictionary): SearchPathFilters | null;
518
184
  /**
@@ -661,4 +327,4 @@ interface GaragemClient {
661
327
  */
662
328
  declare function createGaragemClient(options?: CreateGaragemClientOptions): GaragemClient;
663
329
 
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 };
330
+ export { AppliedSearchChange, AppliedSearchQuery, CmsCollection, CmsEntriesResult, CmsEntry, 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, ListingDetail, ListingFilters, ListingsResult, type LocationFilterInput, QueryListingsFilters, type QueryListingsOptions, QueryListingsParams, QueryListingsResult, RequestNextOptions, type ResolvePublicSiteIdOptions, SEARCH_CSS_RECIPE, SEARCH_CSS_VARS, type SearchListingsOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, SimilarListingsResult, Site, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, formatAreaM2, formatGroupedInteger, formatListingPrice, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getListing, getListings, getSearchUi, getSimilarListings, getSite, isStudioPreviewHost, listingBusinessLabel, listingLookupKey, listingPublicPath, mergeAppliedSearchQueryIntoSearch, parseAppliedSearchQuery, parseGroupedInteger, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, queryListings, reduceAppliedSearchQuery, resolvePublicSiteId, searchListings, serializeAppliedSearchQuery };