@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 +149 -61
- package/dist/index.d.mts +347 -8
- package/dist/index.d.ts +347 -8
- package/dist/index.js +783 -20
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +762 -19
- package/dist/index.mjs.map +1 -1
- package/package.json +19 -6
- package/src/applied-query.ts +42 -0
- package/src/client.ts +174 -29
- package/src/fetchers.ts +259 -16
- package/src/index.ts +61 -0
- package/src/internal/url.ts +4 -2
- package/src/listing-path.ts +19 -0
- package/src/loc-params.ts +36 -0
- package/src/path.ts +73 -0
- package/src/resolve-site-id.ts +55 -0
- package/src/types.ts +187 -4
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.
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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
|
-
|
|
37
|
-
|
|
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.
|
|
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
|
|
54
|
-
|
|
|
55
|
-
| `getListings({ siteId, filters?, next? })`
|
|
56
|
-
| `getListing({ siteId, listingId, next? })`
|
|
57
|
-
| `
|
|
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
|
|
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
|
|
68
|
-
|
|
|
69
|
-
| `createGaragemClient(options)` | Pre-bind `baseUrl`, `siteId`, `fetch`, `next`
|
|
70
|
-
| `GaragemSdkError`
|
|
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
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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({
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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.
|
|
244
|
+
## What's NOT in v0.2
|
|
157
245
|
|
|
158
|
-
- CMS
|
|
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.
|
|
251
|
+
All of these will land additively; the v0.2 surface above will not break.
|