@garagem-ai/site-sdk 0.1.1 → 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/README.md CHANGED
@@ -3,8 +3,7 @@
3
3
  Typed, runtime-agnostic SDK for building custom real estate sites against the
4
4
  Garagem platform.
5
5
 
6
- > **Status:** v0.1.0 alpha — workspace-internal. The public npm release is
7
- > tracked in the Garagem Sites SDK rollout plan.
6
+ > **Status:** v0.2.0 — listings, similar listings, and published CMS reads.
8
7
 
9
8
  ## Install
10
9
 
@@ -21,9 +20,9 @@ pnpm add @garagem-ai/site-sdk
21
20
  import { getListings } from "@garagem-ai/site-sdk";
22
21
 
23
22
  const { listings, total } = await getListings({
24
- siteId: "abc-123",
25
- filters: { city: "São Paulo", limit: 24 },
26
- next: { revalidate: 300, tags: ["site:abc-123:listings"] },
23
+ siteId: "abc-123",
24
+ filters: { city: "São Paulo", limit: 24 },
25
+ next: { revalidate: 300, tags: ["site:abc-123:listings"] },
27
26
  });
28
27
  ```
29
28
 
@@ -33,41 +32,52 @@ const { listings, total } = await getListings({
33
32
  import { createGaragemClient } from "@garagem-ai/site-sdk";
34
33
 
35
34
  export const garagem = createGaragemClient({
36
- siteId: "abc-123",
37
- next: { revalidate: 300 },
35
+ siteId: "abc-123",
36
+ next: { revalidate: 300 },
38
37
  });
39
38
 
40
39
  // Anywhere in your app:
41
40
  const { listings } = await garagem.getListings({ filters: { city: "RJ" } });
42
41
  const detail = await garagem.getListing({ listingId: "xyz" });
42
+ const similar = await garagem.getSimilarListings({
43
+ listingId: "xyz",
44
+ limit: 6,
45
+ });
43
46
  const site = await garagem.getSite({ domain: "imobiliariax.com.br" });
47
+ const posts = await garagem.getCmsEntries({ collection: "blog", limit: 10 });
44
48
  ```
45
49
 
46
- ## What you get in v0.1
50
+ ## What you get in v0.2
47
51
 
48
52
  The SDK ships two layers — a friendly default for 90% of cases, plus a
49
53
  raw escape hatch when you need full control.
50
54
 
51
55
  ### Friendly layer (recommended for most use cases)
52
56
 
53
- | API | Description |
54
- | --- | --- |
55
- | `getListings({ siteId, filters?, next? })` | Paginated listings for a site, with simple `filters` (`city`, `businessType`, `propertyType`, `neighborhood`, `minPrice`, `maxPrice`, `limit`, `offset`) |
56
- | `getListing({ siteId, listingId, next? })` | Full detail of a single listing |
57
- | `getSite({ siteId? \| domain?, next? })` | Public site profile (returns `null` if unknown) |
57
+ | API | Description |
58
+ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
59
+ | `getListings({ siteId, filters?, next? })` | Paginated listings for a site, with simple `filters` (`city`, `businessType`, `propertyType`, `neighborhood`, `minPrice`, `maxPrice`, `limit`, `offset`) |
60
+ | `getListing({ siteId, listingId, next? })` | Full detail of a single listing |
61
+ | `getSimilarListings({ siteId, listingId, limit?, next? })` | Similar listings carousel (same card shape as `getListings`) |
62
+ | `getSite({ siteId? \| domain?, next? })` | Public site profile (returns `null` if unknown) |
63
+ | `getCmsCollections({ siteId })` | List CMS collections |
64
+ | `getCmsCollection({ siteId, slug })` | One CMS collection schema |
65
+ | `getCmsEntries({ siteId, collection, limit?, offset? })` | Published CMS entries only |
66
+ | `getCmsEntry({ siteId, collection, slug })` | One published CMS entry |
67
+ | `resolvePublicSiteId({ host?, fallback? })` | Preview uses `fallback` (`GARAGEM_SITE_ID`); live hosts resolve via `getSite({ domain })` |
58
68
 
59
69
  ### Advanced layer (when the friendly one isn't enough)
60
70
 
61
- | API | Description |
62
- | --- | --- |
63
- | `searchListings({ siteId, params, next? })` | Direct passthrough to the underlying search engine — full param set, raw response (`hits[].document`, `highlight`, `text_match`, etc.). Use for faceted search, multi-field sort, custom grouping. |
71
+ | API | Description |
72
+ | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
73
+ | `searchListings({ siteId, params, next? })` | Direct passthrough to the underlying search engine — full param set, raw response (`hits[].document`, `highlight`, `text_match`, etc.). Use for faceted search, multi-field sort, custom grouping. **Also use this for listing copy in `en`/`es`:** friendly `getListings` / `getListing` always map Portuguese `title`/`description` only; translated fields (`title_en`, `description_en`, `title_es`, `description_es`) appear on the raw Typesense document. See [docs.garagem.ai — Sites API (listing copy)](https://docs.garagem.ai/integracoes/sites-api#título-e-descrição-por-idioma). |
64
74
 
65
75
  ### Cross-cutting
66
76
 
67
- | API | Description |
68
- | --- | --- |
69
- | `createGaragemClient(options)` | Pre-bind `baseUrl`, `siteId`, `fetch`, `next` |
70
- | `GaragemSdkError` | Thrown on non-2xx responses; carries `status` + `url` |
77
+ | API | Description |
78
+ | ------------------------------ | ----------------------------------------------------- |
79
+ | `createGaragemClient(options)` | Pre-bind `baseUrl`, `siteId`, `fetch`, `next` |
80
+ | `GaragemSdkError` | Thrown on non-2xx responses; carries `status` + `url` |
71
81
 
72
82
  All fetchers accept:
73
83
 
@@ -75,6 +85,71 @@ All fetchers accept:
75
85
  - `fetch` — custom fetch implementation (testing, retries, edge runtimes).
76
86
  - `next: { revalidate, tags }` — forwarded directly to the underlying `fetch` for Next.js App Router caching. Ignored on runtimes that don't understand it.
77
87
 
88
+ ## Similar listings example
89
+
90
+ ```tsx
91
+ import { getListing, getSimilarListings } from "@garagem-ai/site-sdk";
92
+
93
+ export default async function ListingPage({
94
+ params,
95
+ }: {
96
+ params: Promise<{ id: string }>;
97
+ }) {
98
+ const { id } = await params;
99
+ const siteId = process.env.GARAGEM_SITE_ID!;
100
+ const listing = await getListing({ siteId, listingId: id });
101
+ const { listings: similar } = await getSimilarListings({
102
+ siteId,
103
+ listingId: id,
104
+ limit: 6,
105
+ next: { revalidate: 300 },
106
+ });
107
+
108
+ return (
109
+ <>
110
+ <h1>{listing.title}</h1>
111
+ <ul>
112
+ {similar.map((l) => (
113
+ <li key={l.id}>{l.title}</li>
114
+ ))}
115
+ </ul>
116
+ </>
117
+ );
118
+ }
119
+ ```
120
+
121
+ ## CMS example
122
+
123
+ ```tsx
124
+ import { getCmsEntries, getCmsEntry } from "@garagem-ai/site-sdk";
125
+
126
+ export default async function BlogIndex() {
127
+ const { entries } = await getCmsEntries({
128
+ siteId: process.env.GARAGEM_SITE_ID!,
129
+ collection: "blog",
130
+ limit: 20,
131
+ next: { revalidate: 60, tags: ["cms:blog"] },
132
+ });
133
+
134
+ return (
135
+ <ul>
136
+ {entries.map((entry) => (
137
+ <li key={entry.id}>{String(entry.fields.title ?? entry.slug)}</li>
138
+ ))}
139
+ </ul>
140
+ );
141
+ }
142
+
143
+ export async function BlogPost({ slug }: { slug: string }) {
144
+ const entry = await getCmsEntry({
145
+ siteId: process.env.GARAGEM_SITE_ID!,
146
+ collection: "blog",
147
+ slug,
148
+ });
149
+ return <article>{/* render entry.fields */}</article>;
150
+ }
151
+ ```
152
+
78
153
  ## App Router example (friendly API)
79
154
 
80
155
  ```tsx
@@ -82,19 +157,19 @@ All fetchers accept:
82
157
  import { getListings } from "@garagem-ai/site-sdk";
83
158
 
84
159
  export default async function Page() {
85
- const { listings } = await getListings({
86
- siteId: process.env.GARAGEM_SITE_ID!,
87
- filters: { businessType: "sale", limit: 24 },
88
- next: { revalidate: 300, tags: ["listings"] },
89
- });
90
-
91
- return (
92
- <ul>
93
- {listings.map((l) => (
94
- <li key={l.id}>{l.title}</li>
95
- ))}
96
- </ul>
97
- );
160
+ const { listings } = await getListings({
161
+ siteId: process.env.GARAGEM_SITE_ID!,
162
+ filters: { businessType: "sale", limit: 24 },
163
+ next: { revalidate: 300, tags: ["listings"] },
164
+ });
165
+
166
+ return (
167
+ <ul>
168
+ {listings.map((l) => (
169
+ <li key={l.id}>{l.title}</li>
170
+ ))}
171
+ </ul>
172
+ );
98
173
  }
99
174
  ```
100
175
 
@@ -106,35 +181,48 @@ webhook handler.
106
181
  `searchListings` exposes the underlying search engine directly. Use
107
182
  when the friendly `filters` shape isn't expressive enough.
108
183
 
184
+ **Multilingual listing copy:** `getListings` and `getListing` return
185
+ Portuguese `title` and `description` only. For English or Spanish copy,
186
+ read `title_en`, `description_en`, `title_es`, and `description_es` from
187
+ `searchListings` hits (or call the Sites API search/property endpoints
188
+ directly) and apply locale fallback in your UI. Details:
189
+ [docs.garagem.ai — Sites API](https://docs.garagem.ai/integracoes/sites-api#título-e-descrição-por-idioma).
190
+
109
191
  ```tsx
110
192
  // app/buscar/page.tsx
111
193
  import { searchListings } from "@garagem-ai/site-sdk";
112
194
 
113
- export default async function Page({ searchParams }: { searchParams: { q?: string } }) {
114
- const result = await searchListings({
115
- siteId: process.env.GARAGEM_SITE_ID!,
116
- params: {
117
- q: searchParams.q ?? "*",
118
- query_by: "title,description,neighborhood",
119
- filter_by: "businessType:=sale && bedrooms:>=2",
120
- sort_by: "price:asc",
121
- facet_by: "neighborhood,propertyType",
122
- per_page: 24,
123
- page: 1,
124
- },
125
- next: { revalidate: 60 },
126
- });
127
-
128
- return (
129
- <>
130
- <p>{result.found} results in {result.search_time_ms}ms</p>
131
- <ul>
132
- {result.hits.map((hit, i) => (
133
- <li key={i}>{String(hit.document.title)}</li>
134
- ))}
135
- </ul>
136
- </>
137
- );
195
+ export default async function Page({
196
+ searchParams,
197
+ }: {
198
+ searchParams: { q?: string };
199
+ }) {
200
+ const result = await searchListings({
201
+ siteId: process.env.GARAGEM_SITE_ID!,
202
+ params: {
203
+ q: searchParams.q ?? "*",
204
+ query_by: "title,description,neighborhood",
205
+ filter_by: "businessType:=sale && bedrooms:>=2",
206
+ sort_by: "price:asc",
207
+ facet_by: "neighborhood,propertyType",
208
+ per_page: 24,
209
+ page: 1,
210
+ },
211
+ next: { revalidate: 60 },
212
+ });
213
+
214
+ return (
215
+ <>
216
+ <p>
217
+ {result.found} results in {result.search_time_ms}ms
218
+ </p>
219
+ <ul>
220
+ {result.hits.map((hit, i) => (
221
+ <li key={i}>{String(hit.document.title)}</li>
222
+ ))}
223
+ </ul>
224
+ </>
225
+ );
138
226
  }
139
227
  ```
140
228
 
@@ -153,11 +241,11 @@ add **publishable keys** with per-tenant rate limits and a domain allowlist —
153
241
  no breaking changes to the call sites, just an additional `publishableKey`
154
242
  option on `createGaragemClient`.
155
243
 
156
- ## What's NOT in v0.1
244
+ ## What's NOT in v0.2
157
245
 
158
- - CMS endpoints (collections / entries) — coming in v0.2.
246
+ - CMS writes / drafts (editor + CMS worker only).
159
247
  - Typesense / InstantSearch helpers — coming as separate `@garagem-ai/site-sdk/search` subpath.
160
248
  - React hooks (`useListings`, `useSearch`, …) — coming as `@garagem-ai/site-sdk/react` subpath.
161
249
  - LiveSession / lead submission helpers.
162
250
 
163
- All of these will land additively; the v0.1 surface above will not break.
251
+ All of these will land additively; the v0.2 surface above will not break.