@garagem-ai/site-sdk 0.7.0 → 0.8.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 +169 -28
- package/dist/index.d.mts +178 -4
- package/dist/index.d.ts +178 -4
- package/dist/index.js +538 -32
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +528 -32
- package/dist/index.mjs.map +1 -1
- package/dist/react.d.mts +6 -1
- package/dist/react.d.ts +6 -1
- package/dist/react.js +140 -14
- package/dist/react.js.map +1 -1
- package/dist/react.mjs +140 -14
- package/dist/react.mjs.map +1 -1
- package/dist/{types-photo-search-OeONNDxl.d.mts → types-photo-search-CmGRj6my.d.mts} +25 -0
- package/dist/{types-photo-search-OeONNDxl.d.ts → types-photo-search-CmGRj6my.d.ts} +25 -0
- package/package.json +1 -1
- package/src/client.ts +23 -0
- package/src/fetchers-photos.ts +98 -0
- package/src/fetchers.ts +92 -29
- package/src/index.ts +31 -2
- package/src/internal/sdk-http.ts +122 -0
- package/src/leads.ts +34 -3
- package/src/listing-photos.ts +312 -0
- package/src/react/types.ts +5 -0
- package/src/react/use-public-search.ts +23 -5
- package/src/resolve-site-id.ts +3 -0
- package/src/studio-contract.ts +74 -0
- package/src/types-photos.ts +46 -0
- package/src/types.ts +11 -0
package/README.md
CHANGED
|
@@ -54,25 +54,27 @@ raw escape hatch when you need full control.
|
|
|
54
54
|
|
|
55
55
|
### Friendly layer (recommended for most use cases)
|
|
56
56
|
|
|
57
|
-
| API
|
|
58
|
-
|
|
|
59
|
-
| `getListings({ siteId, filters?, next? })`
|
|
60
|
-
| `getListing({ siteId, listingId, next? })`
|
|
61
|
-
| `getSimilarListings({ siteId, listingId, limit?, next? })`
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
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
|
+
| `getSimilarByPhoto(siteId, listingId, mediaId, options?)` | "Imóveis com fotos parecidas": listings whose public photos look like one gallery photo. `available: false` when the tenant has no image search — hide the block. |
|
|
63
|
+
| `listingPhotoGroups(listing)` / `listingVisualHighlights(listing)` | Gallery grouped by room (`Sala`, `Quartos`, `Cozinha`, … from each photo's `roomType`) and the deduped visual highlights the photo analysis named most often. |
|
|
64
|
+
| `getSite({ siteId? \| domain?, next? })` | Public site profile (returns `null` if unknown) |
|
|
65
|
+
| `getCmsCollections({ siteId })` | List CMS collections |
|
|
66
|
+
| `getCmsCollection({ siteId, slug })` | One CMS collection schema |
|
|
67
|
+
| `getCmsEntries({ siteId, collection, limit?, offset? })` | Published CMS entries only |
|
|
68
|
+
| `getCmsEntry({ siteId, collection, slug })` | One published CMS entry |
|
|
69
|
+
| `getSearchUi({ siteId, next? })` | Tenant search schema (filters, slugs) |
|
|
70
|
+
| `getLeadUi({ siteId, next? })` | Visit-default lead dialog schema (weekday hours, Sat/Sun flags) |
|
|
71
|
+
| `submitVisitLead({ siteId, listingId, … })` | POST a visit lead (`listing.id` UUID; civil `visitDate` or `Date`/ISO instant normalized in the schedule timezone) |
|
|
72
|
+
| `submitContactLead({ siteId, listingId, … })` | POST a contact lead (no date/time) |
|
|
73
|
+
| `slotsForDate` / `normalizeVisitDate` / `expandVisitSchedule` | Pure schedule helpers (`America/Sao_Paulo`, default Mon–Fri 06:00–22:00) |
|
|
74
|
+
| `listingDetailModel(listing)` | Listing-detail blocks: breadcrumb, location + Maps href, `description` string + toggle label, video/tour overlays. Studio pages map `facts` / `values` via `.label` / `.text` leaves. |
|
|
75
|
+
| `listingDetailFieldsModel(listing, dictionary?)` | Facts, values, and amenity groups that are safe to render: every row has a real label + text; missing condo/IPTU/empty groups are omitted. |
|
|
76
|
+
| `listingAmenityGroups(listing, dictionary?)` | Unit / building amenity labels (`Comodidades`, `Comodidades do condomínio`). Reads `propertyFeatures` + `buildingAmenities` (works when `building` is null). Tenant `getSearchUi().dictionary` first, then the SDK fallback. Studio pages call this helper directly. |
|
|
77
|
+
| `resolvePublicSiteId({ host?, fallback? })` | Preview uses `fallback` (`GARAGEM_SITE_ID`); live hosts resolve via `getSite({ domain })` |
|
|
76
78
|
|
|
77
79
|
### Advanced layer (when the friendly one isn't enough)
|
|
78
80
|
|
|
@@ -82,13 +84,15 @@ raw escape hatch when you need full control.
|
|
|
82
84
|
|
|
83
85
|
### Cross-cutting
|
|
84
86
|
|
|
85
|
-
| API
|
|
86
|
-
|
|
|
87
|
-
| `createGaragemClient(options)` | Pre-bind `baseUrl`, `siteId`, `fetch`, `next`
|
|
88
|
-
| `GaragemSdkError`
|
|
87
|
+
| API | Description |
|
|
88
|
+
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
89
|
+
| `createGaragemClient(options)` / `createClient(options)` | Pre-bind `baseUrl`, `siteId`, `publishableKey`, `fetch`, `next` |
|
|
90
|
+
| `GaragemSdkError` | Thrown on non-2xx responses; `status`, `url`, `reason`, `retryAfter` (seconds, set on 429) |
|
|
89
91
|
|
|
90
92
|
All fetchers accept:
|
|
91
93
|
|
|
94
|
+
- `publishableKey` — optional `pk_live_…` from the site's API pública
|
|
95
|
+
settings. See [Publishable keys & rate limits](#publishable-keys--rate-limits).
|
|
92
96
|
- `baseUrl` — data fetchers default to `https://app.garagem.ai`; `getSite`
|
|
93
97
|
defaults to `https://cdn.fndn.ai/site` so production resolution traverses the
|
|
94
98
|
tenant-locator edge. Override for a custom proxy or staging.
|
|
@@ -174,6 +178,91 @@ export default async function ListingPage({
|
|
|
174
178
|
}
|
|
175
179
|
```
|
|
176
180
|
|
|
181
|
+
## Photo captions, room groups and "imóveis com fotos parecidas"
|
|
182
|
+
|
|
183
|
+
Every photo on `getListing().media` carries the platform's photo analysis when
|
|
184
|
+
the tenant has it: `caption` (AI caption, falling back to the broker's own
|
|
185
|
+
description), `roomType`, `sceneType`, `features`, and an `alt` built from the
|
|
186
|
+
caption. Nothing here calls a model at request time — it is read with the
|
|
187
|
+
listing and cached like the rest of the detail. Photos without analysis keep
|
|
188
|
+
the generic `"<title> - Foto N"` alt and omit the other fields.
|
|
189
|
+
|
|
190
|
+
```tsx
|
|
191
|
+
import {
|
|
192
|
+
getListing,
|
|
193
|
+
getSimilarByPhoto,
|
|
194
|
+
listingPhotoGroups,
|
|
195
|
+
listingVisualHighlights,
|
|
196
|
+
} from "@garagem-ai/site-sdk";
|
|
197
|
+
|
|
198
|
+
export default async function ListingPage({
|
|
199
|
+
params,
|
|
200
|
+
}: {
|
|
201
|
+
params: Promise<{ id: string }>;
|
|
202
|
+
}) {
|
|
203
|
+
const { id } = await params;
|
|
204
|
+
const siteId = process.env.GARAGEM_SITE_ID!;
|
|
205
|
+
const listing = await getListing({ siteId, listingId: id });
|
|
206
|
+
|
|
207
|
+
// "Sala (3) · Quartos (4) · Cozinha (2)" — pt-BR labels, `Outras fotos` last.
|
|
208
|
+
// With no analysis at all you get a single `Outras fotos` group: keep the
|
|
209
|
+
// flat gallery when `groups.length <= 1`.
|
|
210
|
+
const groups = listingPhotoGroups(listing);
|
|
211
|
+
// ["piso de madeira", "pé-direito alto", "vista livre"]
|
|
212
|
+
const highlights = listingVisualHighlights(listing, { limit: 6 });
|
|
213
|
+
|
|
214
|
+
// Listings whose public photos look like the cover photo.
|
|
215
|
+
const cover = listing.media.find((m) => m.type === "image");
|
|
216
|
+
const similar = cover
|
|
217
|
+
? await getSimilarByPhoto(siteId, listing.id, cover.id, {
|
|
218
|
+
limit: 6,
|
|
219
|
+
next: { revalidate: 300 },
|
|
220
|
+
})
|
|
221
|
+
: { available: false, items: [] };
|
|
222
|
+
|
|
223
|
+
return (
|
|
224
|
+
<>
|
|
225
|
+
<ul>
|
|
226
|
+
{highlights.map((h) => (
|
|
227
|
+
<li key={h}>{h}</li>
|
|
228
|
+
))}
|
|
229
|
+
</ul>
|
|
230
|
+
{groups.map((group) => (
|
|
231
|
+
<section key={group.key}>
|
|
232
|
+
<h2>
|
|
233
|
+
{group.label} ({group.photos.length})
|
|
234
|
+
</h2>
|
|
235
|
+
{group.photos.map((photo) => (
|
|
236
|
+
<img key={photo.id} src={photo.src} alt={photo.alt} />
|
|
237
|
+
))}
|
|
238
|
+
</section>
|
|
239
|
+
))}
|
|
240
|
+
{similar.available && similar.items.length > 0 && (
|
|
241
|
+
<section>
|
|
242
|
+
<h2>Imóveis com fotos parecidas</h2>
|
|
243
|
+
{similar.items.map(({ listing: l, matchedPhoto }) => (
|
|
244
|
+
<a key={l.id} href={l.path}>
|
|
245
|
+
<img src={matchedPhoto.src} alt={matchedPhoto.alt} />
|
|
246
|
+
{l.title}
|
|
247
|
+
</a>
|
|
248
|
+
))}
|
|
249
|
+
</section>
|
|
250
|
+
)}
|
|
251
|
+
</>
|
|
252
|
+
);
|
|
253
|
+
}
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
`getSimilarByPhoto` returns `{ available, items }`. `available` is `false`
|
|
257
|
+
when the site's tenant has not enabled image search, and when `photo.id` is
|
|
258
|
+
not a media UUID — `getListing` uses `image-N` when Typesense has no id for
|
|
259
|
+
that photo and `external-N` for video or tour. That returns locally, without
|
|
260
|
+
a request, so the example above hides the section instead of throwing. Items
|
|
261
|
+
are `{ listing, matchedPhoto: { id, src, alt, caption, distance } }` with the
|
|
262
|
+
same card shape as `getListings`. Only public photos of public, active
|
|
263
|
+
listings are compared; the reference listing (and its sale/rental twin) is
|
|
264
|
+
never returned. `limit` defaults to 6 and caps at 12.
|
|
265
|
+
|
|
177
266
|
## CMS example
|
|
178
267
|
|
|
179
268
|
```tsx
|
|
@@ -290,12 +379,64 @@ Works wherever `fetch` is available:
|
|
|
290
379
|
- Edge runtime (Vercel Edge, Cloudflare Workers, Deno)
|
|
291
380
|
- Browsers (use carefully — see "Public keys" below)
|
|
292
381
|
|
|
293
|
-
##
|
|
382
|
+
## Publishable keys & rate limits
|
|
383
|
+
|
|
384
|
+
Calls to `/api/sites/{siteId}/*` stay anonymous when you pass no key. A
|
|
385
|
+
**publishable key** (`pk_live_…`) is not a secret: it ships in the browser
|
|
386
|
+
bundle and only tells Foundation which site to meter. Create or rotate it
|
|
387
|
+
in Garagem at **Configurações → Sites → the site → API pública**
|
|
388
|
+
(`/configuracoes/sites/[siteId]`). Copy it into the client:
|
|
389
|
+
|
|
390
|
+
```ts
|
|
391
|
+
import { createClient } from "@garagem-ai/site-sdk";
|
|
392
|
+
|
|
393
|
+
export const garagem = createClient({
|
|
394
|
+
siteId: process.env.NEXT_PUBLIC_GARAGEM_SITE_ID,
|
|
395
|
+
publishableKey: process.env.NEXT_PUBLIC_GARAGEM_PUBLISHABLE_KEY,
|
|
396
|
+
});
|
|
397
|
+
```
|
|
294
398
|
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
399
|
+
`createClient` is an alias of `createGaragemClient`. The same
|
|
400
|
+
`publishableKey` option exists on every fetcher (`getListings`,
|
|
401
|
+
`getListing`, `getSite`, `getSearchUi`, `queryListings`, `searchListings`,
|
|
402
|
+
the CMS helpers, `getLeadUi`, `submitVisitLead`, `submitContactLead`) and
|
|
403
|
+
on `usePublicSearch`. The SDK sends it as `X-Garagem-Publishable-Key`.
|
|
404
|
+
`Authorization: Bearer pk_live_…` is accepted too. A blank value is treated
|
|
405
|
+
as no key.
|
|
406
|
+
|
|
407
|
+
### Compatibility
|
|
408
|
+
|
|
409
|
+
| Request | Result |
|
|
410
|
+
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
411
|
+
| Site has no key, request has no key | Served. Anonymous per-IP budget. |
|
|
412
|
+
| Site has a key, request has no key | Served. Stricter anonymous per-IP budget (older bundles keep working). |
|
|
413
|
+
| Request key matches this site | Served. Shared per-site budget. |
|
|
414
|
+
| Request key is present but wrong | **401** `GaragemSdkError` with `reason: "invalid_publishable_key"`. A key never opens another site. |
|
|
415
|
+
| Browser `Origin` / `Referer` not on the site allowlist | **403** `reason: "origin_not_allowed"`. Empty allowlist means any origin. Requests with neither header (server-to-server, RSC) are not origin-checked. |
|
|
416
|
+
| Budget exceeded | **429** `reason: "rate_limited"`. `error.retryAfter` is seconds (also the `Retry-After` header). |
|
|
417
|
+
|
|
418
|
+
Lead POST (`submitVisitLead` / `submitContactLead`) throws `LeadSubmitError`
|
|
419
|
+
instead: `code: "unauthorized"` on 401, `code: "rate_limited"` on 429, with
|
|
420
|
+
`retryAfter` and `retryAfterSeconds`.
|
|
421
|
+
|
|
422
|
+
### Defaults (hits per 60 seconds)
|
|
423
|
+
|
|
424
|
+
| Bucket | With key | No key configured | Key configured, request omitted it |
|
|
425
|
+
| ------------------------------------------------------------------------ | -------: | ----------------: | ---------------------------------: |
|
|
426
|
+
| `listings` (index, CMS entry lists) | 600 | 120 | 30 |
|
|
427
|
+
| `search` | 600 | 120 | 30 |
|
|
428
|
+
| `detail` (listing, similar, CMS entry) | 1200 | 300 | 60 |
|
|
429
|
+
| `config` (search UI, lead UI, locations, public config, CMS collections) | 300 | 120 | 30 |
|
|
430
|
+
|
|
431
|
+
Responses include `RateLimit-Limit`, `RateLimit-Remaining`,
|
|
432
|
+
`RateLimit-Reset`, and `RateLimit-Policy` (`{limit};w=60`). `Retry-After`
|
|
433
|
+
is added on a deny. The limiter is shared across Foundation instances in
|
|
434
|
+
the cell (cell-local Valkey). If that cache is down, the same window is
|
|
435
|
+
enforced in memory on the instance that handled the request.
|
|
436
|
+
|
|
437
|
+
First-party traffic from the Garagem site proxy is exempt. Set
|
|
438
|
+
`PUBLIC_SITE_RATE_LIMIT_MODE=observe` to count without denying, or `off`
|
|
439
|
+
to skip metering. Key and origin checks still run in both modes.
|
|
299
440
|
|
|
300
441
|
## Search UI (`@garagem-ai/site-sdk/react`)
|
|
301
442
|
|
package/dist/index.d.mts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { F as FetchLike, R as RequestNextOptions, L as ListingDetail, a as ListingLocation, b as ListingMedia, c as ListingBusinessType, d as ListingPriceVisibility, e as Listing, S as SearchPathFilters, f as SearchUiDictionary, Q as QueryListingsFilters, A as AppliedSearchQuery, g as AppliedSearchChange, h as ListingFilters, i as ListingsResult, j as Site, k as SearchListingsParams, l as SearchListingsResult, m as SearchUi, n as QueryListingsParams, o as QueryListingsResult, p as SimilarListingsResult, C as CmsCollection, q as CmsEntriesResult, r as CmsEntry, P as PhotoSearchParams, s as PhotoSearchResult, t as PhotoSearchItem, u as ListingWithMatchedPhoto, M as MatchedListingPhoto } from './types-photo-search-
|
|
2
|
-
export { v as CmsEntryStatus, w as CmsFieldDefinition, x as CmsFieldType, y as CmsSeoData, z as FORBIDDEN_SEARCH_QUERY_KEYS, G as GaragemSdkError, B as GetCmsCollectionOptions, D as GetCmsCollectionsOptions, E as GetCmsEntriesOptions, H as GetCmsEntryOptions, I as GetListingOptions, J as GetListingsOptions, K as GetSearchUiOptions, N as GetSimilarListingsOptions, O as GetSiteOptions, T as ListingPropertySummary, U as LocationNameTables, V as QueryListingsLocation, W as QueryListingsOptions, X as SEARCH_EMPTY_COPY, Y as SEARCH_SORT_RELEVANCE, Z as SearchChromeModel, _ as SearchListingsOptions, $ as SearchPathLocation, a0 as SearchUiFilter, a1 as SearchUiOption, a2 as TOOLBAR_PRIMARY_FILTER_IDS, a3 as applyPathFilter, a4 as buildQueryListingsParams, a5 as canonicalizeSearchHref, a6 as clearStagedPathFilters, a7 as countFacetChoices, a8 as countOptionLabel, a9 as displayPathLocation, aa as getCmsCollection, ab as getCmsCollections, ac as getCmsEntries, ad as getCmsEntry, ae as getListing, af as getListings, ag as getSearchUi, ah as getSimilarListings, ai as getSite, aj as hrefForAppliedChange, ak as hrefForPathFilters, al as hrefWithExplicitPage, am as isListingDetailPath, an as paginationPages, ao as pathFilterHasOption, ap as pathFilterValue, aq as publicSearchHref, ar as queryListings, as as rangeDraftFromPath, at as readPublicSearch, au as searchChromeModel, av as searchHrefUsesLegacyFilterQuery, aw as searchListings, ax as searchResultsHeading, ay as searchSortOptions, az as toolbarFilterIds, aA as visibleSearchFilters } from './types-photo-search-
|
|
1
|
+
import { F as FetchLike, R as RequestNextOptions, L as ListingDetail, a as ListingLocation, b as ListingMedia, c as ListingBusinessType, d as ListingPriceVisibility, e as Listing, S as SearchPathFilters, f as SearchUiDictionary, Q as QueryListingsFilters, A as AppliedSearchQuery, g as AppliedSearchChange, h as ListingFilters, i as ListingsResult, j as Site, k as SearchListingsParams, l as SearchListingsResult, m as SearchUi, n as QueryListingsParams, o as QueryListingsResult, p as SimilarListingsResult, C as CmsCollection, q as CmsEntriesResult, r as CmsEntry, P as PhotoSearchParams, s as PhotoSearchResult, t as PhotoSearchItem, u as ListingWithMatchedPhoto, M as MatchedListingPhoto } from './types-photo-search-CmGRj6my.mjs';
|
|
2
|
+
export { v as CmsEntryStatus, w as CmsFieldDefinition, x as CmsFieldType, y as CmsSeoData, z as FORBIDDEN_SEARCH_QUERY_KEYS, G as GaragemSdkError, B as GetCmsCollectionOptions, D as GetCmsCollectionsOptions, E as GetCmsEntriesOptions, H as GetCmsEntryOptions, I as GetListingOptions, J as GetListingsOptions, K as GetSearchUiOptions, N as GetSimilarListingsOptions, O as GetSiteOptions, T as ListingPropertySummary, U as LocationNameTables, V as QueryListingsLocation, W as QueryListingsOptions, X as SEARCH_EMPTY_COPY, Y as SEARCH_SORT_RELEVANCE, Z as SearchChromeModel, _ as SearchListingsOptions, $ as SearchPathLocation, a0 as SearchUiFilter, a1 as SearchUiOption, a2 as TOOLBAR_PRIMARY_FILTER_IDS, a3 as applyPathFilter, a4 as buildQueryListingsParams, a5 as canonicalizeSearchHref, a6 as clearStagedPathFilters, a7 as countFacetChoices, a8 as countOptionLabel, a9 as displayPathLocation, aa as getCmsCollection, ab as getCmsCollections, ac as getCmsEntries, ad as getCmsEntry, ae as getListing, af as getListings, ag as getSearchUi, ah as getSimilarListings, ai as getSite, aj as hrefForAppliedChange, ak as hrefForPathFilters, al as hrefWithExplicitPage, am as isListingDetailPath, an as paginationPages, ao as pathFilterHasOption, ap as pathFilterValue, aq as publicSearchHref, ar as queryListings, as as rangeDraftFromPath, at as readPublicSearch, au as searchChromeModel, av as searchHrefUsesLegacyFilterQuery, aw as searchListings, ax as searchResultsHeading, ay as searchSortOptions, az as toolbarFilterIds, aA as visibleSearchFilters } from './types-photo-search-CmGRj6my.mjs';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Visit-lead schedule: hours in, slots out. Pure — no fetch, no React.
|
|
@@ -68,6 +68,8 @@ type GetLeadUiOptions = {
|
|
|
68
68
|
baseUrl?: string;
|
|
69
69
|
fetch?: FetchLike;
|
|
70
70
|
next?: RequestNextOptions;
|
|
71
|
+
/** Site publishable key (`pk_live_…`). Not a secret. */
|
|
72
|
+
publishableKey?: string;
|
|
71
73
|
};
|
|
72
74
|
type LeadContact = {
|
|
73
75
|
name: string;
|
|
@@ -79,6 +81,8 @@ type LeadSubmitBase = LeadContact & {
|
|
|
79
81
|
siteId?: string | Promise<string>;
|
|
80
82
|
baseUrl?: string;
|
|
81
83
|
fetch?: FetchLike;
|
|
84
|
+
/** Site publishable key (`pk_live_…`). Not a secret. */
|
|
85
|
+
publishableKey?: string;
|
|
82
86
|
listingId: string;
|
|
83
87
|
/**
|
|
84
88
|
* Active listing modality (`sale` | `rental` | `rent`). Always pass
|
|
@@ -102,11 +106,13 @@ type LeadSubmitResult = {
|
|
|
102
106
|
status: 202;
|
|
103
107
|
id: string;
|
|
104
108
|
};
|
|
105
|
-
type LeadSubmitErrorCode = "invalid_listing_id" | "invalid_contact" | "invalid_slot" | "rate_limited" | "not_found" | "http" | "network";
|
|
109
|
+
type LeadSubmitErrorCode = "invalid_listing_id" | "invalid_contact" | "invalid_slot" | "unauthorized" | "rate_limited" | "not_found" | "http" | "network";
|
|
106
110
|
declare class LeadSubmitError extends Error {
|
|
107
111
|
readonly code: LeadSubmitErrorCode;
|
|
108
112
|
readonly status?: number;
|
|
109
113
|
readonly retryAfterSeconds?: number;
|
|
114
|
+
/** Seconds to wait. Same value as `retryAfterSeconds`; `null` when unset. */
|
|
115
|
+
readonly retryAfter: number | null;
|
|
110
116
|
constructor(message: string, info: {
|
|
111
117
|
code: LeadSubmitErrorCode;
|
|
112
118
|
status?: number;
|
|
@@ -442,6 +448,8 @@ interface ResolvePublicSiteIdOptions {
|
|
|
442
448
|
fallback?: string | null;
|
|
443
449
|
baseUrl?: string;
|
|
444
450
|
fetch?: FetchLike;
|
|
451
|
+
/** Forwarded to `getSite` when the live host is resolved. */
|
|
452
|
+
publishableKey?: string;
|
|
445
453
|
}
|
|
446
454
|
declare function isStudioPreviewHost(host: string): boolean;
|
|
447
455
|
/**
|
|
@@ -502,6 +510,24 @@ declare const STUDIO_SDK_CONTRACT: {
|
|
|
502
510
|
*/
|
|
503
511
|
readonly unpublishedPhoneExports: readonly [];
|
|
504
512
|
readonly amenityExports: readonly ["listingAmenityGroups"];
|
|
513
|
+
/**
|
|
514
|
+
* Prompt-safe photo helpers on `minNpmVersion`. Empty until the release
|
|
515
|
+
* that carries `getSimilarByPhoto` / `listingPhotoGroups` /
|
|
516
|
+
* `listingVisualHighlights` is on npm; then bump the pin, move the names
|
|
517
|
+
* here from `unpublishedPhotoExports`, and `studioPhotoInstruction()`
|
|
518
|
+
* starts teaching the gallery-by-room, highlight chips, and
|
|
519
|
+
* "imóveis com fotos parecidas" blocks. The caption-based `media[].alt` /
|
|
520
|
+
* `media[].caption` fields are API data (not tarball exports) and are
|
|
521
|
+
* documented regardless of the pin.
|
|
522
|
+
*/
|
|
523
|
+
readonly photoExports: readonly [];
|
|
524
|
+
/**
|
|
525
|
+
* Photo helpers in the repo but not on `minNpmVersion`. Prompts,
|
|
526
|
+
* completeness, and repair text must not mention these until the pin
|
|
527
|
+
* bumps — v0 installs the pin and the ESM loader throws on missing named
|
|
528
|
+
* exports.
|
|
529
|
+
*/
|
|
530
|
+
readonly unpublishedPhotoExports: readonly ["getSimilarByPhoto", "listingPhotoGroups", "listingVisualHighlights", "photoRoomLabel"];
|
|
505
531
|
/**
|
|
506
532
|
* Names already on the pinned npm tarball (`minNpmVersion`) — safe for
|
|
507
533
|
* Studio prompts and completeness. Includes `visibleSearchFilters` +
|
|
@@ -567,10 +593,26 @@ declare function coerceNpmVersion(raw: unknown): string | null;
|
|
|
567
593
|
declare function compareSemver(a: string, b: string): number;
|
|
568
594
|
declare function parseReactSdkNamedImports(source: string): string[];
|
|
569
595
|
declare function unavailableReactImports(source: string, pin: string): string[];
|
|
596
|
+
/**
|
|
597
|
+
* Studio copy for the public site API key. Names only exports that already
|
|
598
|
+
* exist on `minNpmVersion` (`createGaragemClient`, `GaragemSdkError`,
|
|
599
|
+
* `usePublicSearch`, the lead helpers). `publishableKey` is an extra option
|
|
600
|
+
* older tarballs ignore, so generated sites keep working before this SDK
|
|
601
|
+
* version is published.
|
|
602
|
+
*/
|
|
603
|
+
declare function studioPublishableKeyInstruction(): string;
|
|
570
604
|
declare function studioSdkPinInstruction(): string;
|
|
571
605
|
declare function studioLeadInstruction(): string;
|
|
572
606
|
declare function studioListingCardInstruction(): string;
|
|
573
607
|
declare function studioListingDetailInstruction(): string;
|
|
608
|
+
/**
|
|
609
|
+
* Listing-detail photo intelligence, gated on the published pin. The base
|
|
610
|
+
* sentence (caption-based `alt` / optional `caption` on gallery photos) is
|
|
611
|
+
* API data and always applies; each helper block appears only when its
|
|
612
|
+
* export is in `published` (see `STUDIO_SDK_CONTRACT.photoExports`).
|
|
613
|
+
*/
|
|
614
|
+
declare function studioPhotoInstructionFor(published: readonly string[]): string;
|
|
615
|
+
declare function studioPhotoInstruction(): string;
|
|
574
616
|
declare function studioAmenityInstruction(): string;
|
|
575
617
|
declare function studioSearchInstruction(): string;
|
|
576
618
|
/** True when the pinned tarball ships the market-data helpers. */
|
|
@@ -599,6 +641,12 @@ interface CreateGaragemClientOptions {
|
|
|
599
641
|
baseUrl?: string;
|
|
600
642
|
/** Pre-bind a site so each call doesn't repeat it. */
|
|
601
643
|
siteId?: string;
|
|
644
|
+
/**
|
|
645
|
+
* Publishable key (`pk_live_…`) from the site's API pública settings.
|
|
646
|
+
* Sent as `X-Garagem-Publishable-Key` on every request. Not a secret.
|
|
647
|
+
* Omit it to keep the anonymous per-IP budget.
|
|
648
|
+
*/
|
|
649
|
+
publishableKey?: string;
|
|
602
650
|
/** Custom fetch implementation. */
|
|
603
651
|
fetch?: FetchLike;
|
|
604
652
|
/** Default Next.js caching hints applied to every request. */
|
|
@@ -701,6 +749,132 @@ interface GaragemClient {
|
|
|
701
749
|
* exported for the no-client style.
|
|
702
750
|
*/
|
|
703
751
|
declare function createGaragemClient(options?: CreateGaragemClientOptions): GaragemClient;
|
|
752
|
+
/**
|
|
753
|
+
* Alias of {@link createGaragemClient}. `createClient({ publishableKey })`
|
|
754
|
+
* binds the key the same way.
|
|
755
|
+
*/
|
|
756
|
+
declare const createClient: typeof createGaragemClient;
|
|
757
|
+
|
|
758
|
+
/**
|
|
759
|
+
* Photo intelligence types for the public Sites API.
|
|
760
|
+
*
|
|
761
|
+
* `ListingMedia` (in `./types`) carries the per-photo analysis on the listing
|
|
762
|
+
* detail; these shapes cover the "imóveis com fotos parecidas" endpoint and
|
|
763
|
+
* the headless photo helpers. Additive contract, never breaking.
|
|
764
|
+
*/
|
|
765
|
+
|
|
766
|
+
/** The photo of a similar listing that matched the reference photo. */
|
|
767
|
+
interface SimilarPhotoMatch {
|
|
768
|
+
/** Media id of the matched photo on the similar listing. */
|
|
769
|
+
id: string;
|
|
770
|
+
src: string;
|
|
771
|
+
alt: string;
|
|
772
|
+
/** AI caption of the matched photo, when it has one. */
|
|
773
|
+
caption: string | null;
|
|
774
|
+
/** Typesense cosine `vector_distance`; lower is closer. `null` when unknown. */
|
|
775
|
+
distance: number | null;
|
|
776
|
+
}
|
|
777
|
+
interface SimilarByPhotoItem {
|
|
778
|
+
/** Same card shape as `getListings`. */
|
|
779
|
+
listing: Listing;
|
|
780
|
+
matchedPhoto: SimilarPhotoMatch;
|
|
781
|
+
}
|
|
782
|
+
/** Response of `getSimilarByPhoto`. */
|
|
783
|
+
interface SimilarByPhotoResult {
|
|
784
|
+
/**
|
|
785
|
+
* `false` when the site's tenant has no image search, or when `mediaId`
|
|
786
|
+
* is not a media UUID (the `image-N` / `external-N` gallery keys). Hide
|
|
787
|
+
* the block instead of rendering an empty carousel.
|
|
788
|
+
*/
|
|
789
|
+
available: boolean;
|
|
790
|
+
items: SimilarByPhotoItem[];
|
|
791
|
+
}
|
|
792
|
+
/** Gallery photos of one room type, in gallery order. */
|
|
793
|
+
interface ListingPhotoGroup {
|
|
794
|
+
/** Normalized key (`quarto`, `sala`, `cozinha`, …; `outros` for unknown). */
|
|
795
|
+
key: string;
|
|
796
|
+
/** pt-BR label ready to render (`Quartos`, `Sala`, `Cozinha`, …). */
|
|
797
|
+
label: string;
|
|
798
|
+
photos: ListingMedia[];
|
|
799
|
+
}
|
|
800
|
+
|
|
801
|
+
/**
|
|
802
|
+
* "Imóveis com fotos parecidas" fetcher.
|
|
803
|
+
*
|
|
804
|
+
* Self-contained beside `./fetchers`: same base-URL / fetch / `next`
|
|
805
|
+
* conventions, positional ids so a gallery click can call
|
|
806
|
+
* `getSimilarByPhoto(siteId, listing.id, photo.id)` directly.
|
|
807
|
+
*/
|
|
808
|
+
|
|
809
|
+
interface GetSimilarByPhotoOptions {
|
|
810
|
+
/** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
|
|
811
|
+
baseUrl?: string;
|
|
812
|
+
/** Override the fetch implementation (testing, edge runtimes, retries). */
|
|
813
|
+
fetch?: FetchLike;
|
|
814
|
+
/** Next.js App Router caching hints. Ignored elsewhere. */
|
|
815
|
+
next?: RequestNextOptions;
|
|
816
|
+
/** Max similar listings to return (API default 6, cap 12). */
|
|
817
|
+
limit?: number;
|
|
818
|
+
}
|
|
819
|
+
/**
|
|
820
|
+
* Listings whose public photos look like one photo of `listingId`.
|
|
821
|
+
*
|
|
822
|
+
* `available` is `false` when the site's tenant has no image search, and
|
|
823
|
+
* when `mediaId` is not a media UUID (`image-N`, `external-N`, or any other
|
|
824
|
+
* gallery key `getListing` assigned). That case returns locally, without a
|
|
825
|
+
* request, so a page that passes `photo.id` hides the block instead of
|
|
826
|
+
* throwing. Items carry the public card model plus the photo that matched.
|
|
827
|
+
*
|
|
828
|
+
* @example
|
|
829
|
+
* const { available, items } = await getSimilarByPhoto(
|
|
830
|
+
* siteId,
|
|
831
|
+
* listing.id,
|
|
832
|
+
* photo.id,
|
|
833
|
+
* { limit: 6, next: { revalidate: 300 } }
|
|
834
|
+
* );
|
|
835
|
+
*/
|
|
836
|
+
declare function getSimilarByPhoto(siteId: string, listingId: string, mediaId: string, options?: GetSimilarByPhotoOptions): Promise<SimilarByPhotoResult>;
|
|
837
|
+
|
|
838
|
+
/**
|
|
839
|
+
* Headless photo helpers for the listing detail.
|
|
840
|
+
*
|
|
841
|
+
* `listingPhotoGroups` turns the gallery into "Sala (3) · Quartos (4) ·
|
|
842
|
+
* Cozinha (2)" sections from the per-photo `roomType`; `listingVisualHighlights`
|
|
843
|
+
* surfaces the visual features the analysis named most often. Both are pure
|
|
844
|
+
* and only read `ListingDetail.media`.
|
|
845
|
+
*/
|
|
846
|
+
|
|
847
|
+
declare const PHOTO_GROUP_OTHER_KEY = "outros";
|
|
848
|
+
declare const PHOTO_GROUP_OTHER_LABEL = "Outras fotos";
|
|
849
|
+
/**
|
|
850
|
+
* Group key + pt-BR label for a photo `roomType`. Unknown rooms keep their
|
|
851
|
+
* own (capitalized) label; empty / "other" values go to `Outras fotos`.
|
|
852
|
+
*/
|
|
853
|
+
declare function photoRoomLabel(roomType: string | null | undefined): {
|
|
854
|
+
key: string;
|
|
855
|
+
label: string;
|
|
856
|
+
};
|
|
857
|
+
/**
|
|
858
|
+
* Gallery photos grouped by room, in first-appearance order with `Outras
|
|
859
|
+
* fotos` last. Videos and tours are skipped. A listing with no analysis at
|
|
860
|
+
* all yields a single `Outras fotos` group (or `[]` when it has no photos),
|
|
861
|
+
* so callers can fall back to the flat gallery when `groups.length <= 1`.
|
|
862
|
+
*/
|
|
863
|
+
declare function listingPhotoGroups(listing: {
|
|
864
|
+
media?: ListingMedia[] | null;
|
|
865
|
+
}): ListingPhotoGroup[];
|
|
866
|
+
interface ListingVisualHighlightsOptions {
|
|
867
|
+
/** Max highlights to return. Default 8. */
|
|
868
|
+
limit?: number;
|
|
869
|
+
}
|
|
870
|
+
/**
|
|
871
|
+
* Distinct visual highlights across the gallery, most frequent first (ties
|
|
872
|
+
* keep gallery order). Case- and accent-insensitive dedupe; the first
|
|
873
|
+
* spelling seen wins.
|
|
874
|
+
*/
|
|
875
|
+
declare function listingVisualHighlights(listing: {
|
|
876
|
+
media?: ListingMedia[] | null;
|
|
877
|
+
}, options?: ListingVisualHighlightsOptions): string[];
|
|
704
878
|
|
|
705
879
|
/**
|
|
706
880
|
* Market-data types for the public site.
|
|
@@ -973,4 +1147,4 @@ declare function resolveMatchedCoverPhoto(photo: MatchedListingPhoto | null | un
|
|
|
973
1147
|
*/
|
|
974
1148
|
declare function applyMatchedPhotoCover<T extends Listing>(cards: ReadonlyArray<T>, photoResults: PhotoSearchResult | ReadonlyArray<PhotoSearchItem> | null | undefined, options?: ApplyMatchedPhotoCoverOptions): Array<T & ListingWithMatchedPhoto>;
|
|
975
1149
|
|
|
976
|
-
export { AMENITY_FALLBACK_LABELS, type AmenityLabelDictionary, type AmenityLabelOption, AppliedSearchChange, AppliedSearchQuery, type ApplyMatchedPhotoCoverOptions, CmsCollection, CmsEntriesResult, CmsEntry, type ContactLeadInput, type CreateGaragemClientOptions, DEFAULT_PHONE_COUNTRY_CODE, FetchLike, type GaragemClient, type GetLeadUiOptions, type GetListingMarketPositionOptions, type GetNeighborhoodSummaryOptions, type HHmm, LISTING_AMENITY_TITLES, LISTING_DESCRIPTION_CLAMP, type LeadContact, type LeadField, type LeadFieldId, LeadSubmitError, type LeadSubmitErrorCode, type LeadSubmitResult, type LeadUi, Listing, type ListingAmenityGroup, type ListingAmenityGroupKey, type ListingAmenitySource, type ListingBreadcrumbCrumb, ListingBusinessType, type ListingCardModel, type ListingDescriptionPreview, ListingDetail, type ListingDetailFieldsModel, type ListingDetailFieldsSource, type ListingDetailModel, type ListingFact, ListingFilters, ListingLocation, type ListingLocationBlock, type ListingMarketPosition, ListingMedia, type ListingMediaOverlay, ListingPriceVisibility, type ListingValue, ListingWithMatchedPhoto, ListingsResult, type LocationFilterInput, MATCHED_PHOTO_COVER_MAX_DISTANCE, MAX_NATIONAL_PHONE_DIGITS, type MarketListingType, type MarketPriceBand, type MarketPropertyType, type MarketUnavailableReason, MatchedListingPhoto, type NeighborhoodSummary, type NeighborhoodSummaryQuery, PHONE_COUNTRIES, PHOTO_SEARCH_MIN_QUERY_LENGTH, type ParsedPhoneInput, type PhoneCountry, PhotoSearchItem, PhotoSearchParams, PhotoSearchResult, type PriceEstimate, type PriceEstimateConfidence, type PriceEstimateInput, QueryListingsFilters, QueryListingsParams, QueryListingsResult, RequestNextOptions, type RequestPriceEstimateOptions, type ResolvePublicSiteIdOptions, STUDIO_DEFAULT_VISIT_SCHEDULE, STUDIO_SDK_CONTRACT, STUDIO_SDK_PACKAGE, STUDIO_SITE_LAYOUT, type SearchListingPhotosOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, SimilarListingsResult, Site, type StudioSdkContract, VISIT_TIME_ZONE, type VisitHours, type VisitLeadInput, type VisitSchedule, type VisitScheduleConfig, applyMatchedPhotoCover, coerceNpmVersion, collapseDuplicatedBrazilianMobileNine, compareSemver, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, defaultPhoneCountry, expandVisitSchedule, expandVisitTimeSlots, findPhoneCountry, formatAreaM2, formatGroupedInteger, formatListingPrice, formatPhoneNational, getLeadUi, getListingMarketPosition, getNeighborhoodSummary, hasShowcaseLeadsPostUrl, isPhotoSearchOnPin, isStudioPreviewHost, isValidPhone, isVisitSlotAllowed, labelAmenities, listingAmenityGroups, listingBreadcrumb, listingBusinessLabel, listingDescriptionPreview, listingDetailFieldsModel, listingDetailModel, listingFacts, listingLocationBlock, listingLocationLabel, listingLookupKey, listingMapsHref, listingMediaOverlays, listingPublicPath, listingValues, marketExportsAvailableAt, marketPositionLabel, mergeAppliedSearchQueryIntoSearch, nationalPhoneDigits, normalizeVisitDate, normalizeVisitTime, parseAppliedSearchQuery, parseGroupedInteger, parsePhoneInput, parseReactSdkNamedImports, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, phoneCountrySearchValue, photoSearchUrl, priceBandLabel, reduceAppliedSearchQuery, remaskPhoneForCountry, requestPriceEstimate, resolveMatchedCoverPhoto, resolvePublicSiteId, searchListingPhotos, serializeAppliedSearchQuery, slotsForDate, studioAmenityInstruction, studioChromeInstruction, studioCodegenContractViolations, studioDefaultLeadUi, studioLayoutInstruction, studioLeadInstruction, studioListingCardInstruction, studioListingDetailInstruction, studioMarketInstruction, studioPhotoSearchInstruction, studioSdkPinInstruction, studioSearchInstruction, studioSearchLandmarkInstruction, studioSiteWidthCss, submitContactLead, submitVisitLead, toE164, toListingCardModel, truncateNationalPhoneDigits, unavailableReactImports };
|
|
1150
|
+
export { AMENITY_FALLBACK_LABELS, type AmenityLabelDictionary, type AmenityLabelOption, AppliedSearchChange, AppliedSearchQuery, type ApplyMatchedPhotoCoverOptions, CmsCollection, CmsEntriesResult, CmsEntry, type ContactLeadInput, type CreateGaragemClientOptions, DEFAULT_PHONE_COUNTRY_CODE, FetchLike, type GaragemClient, type GetLeadUiOptions, type GetListingMarketPositionOptions, type GetNeighborhoodSummaryOptions, type GetSimilarByPhotoOptions, type HHmm, LISTING_AMENITY_TITLES, LISTING_DESCRIPTION_CLAMP, type LeadContact, type LeadField, type LeadFieldId, LeadSubmitError, type LeadSubmitErrorCode, type LeadSubmitResult, type LeadUi, Listing, type ListingAmenityGroup, type ListingAmenityGroupKey, type ListingAmenitySource, type ListingBreadcrumbCrumb, ListingBusinessType, type ListingCardModel, type ListingDescriptionPreview, ListingDetail, type ListingDetailFieldsModel, type ListingDetailFieldsSource, type ListingDetailModel, type ListingFact, ListingFilters, ListingLocation, type ListingLocationBlock, type ListingMarketPosition, ListingMedia, type ListingMediaOverlay, type ListingPhotoGroup, ListingPriceVisibility, type ListingValue, type ListingVisualHighlightsOptions, ListingWithMatchedPhoto, ListingsResult, type LocationFilterInput, MATCHED_PHOTO_COVER_MAX_DISTANCE, MAX_NATIONAL_PHONE_DIGITS, type MarketListingType, type MarketPriceBand, type MarketPropertyType, type MarketUnavailableReason, MatchedListingPhoto, type NeighborhoodSummary, type NeighborhoodSummaryQuery, PHONE_COUNTRIES, PHOTO_GROUP_OTHER_KEY, PHOTO_GROUP_OTHER_LABEL, PHOTO_SEARCH_MIN_QUERY_LENGTH, type ParsedPhoneInput, type PhoneCountry, PhotoSearchItem, PhotoSearchParams, PhotoSearchResult, type PriceEstimate, type PriceEstimateConfidence, type PriceEstimateInput, QueryListingsFilters, QueryListingsParams, QueryListingsResult, RequestNextOptions, type RequestPriceEstimateOptions, type ResolvePublicSiteIdOptions, STUDIO_DEFAULT_VISIT_SCHEDULE, STUDIO_SDK_CONTRACT, STUDIO_SDK_PACKAGE, STUDIO_SITE_LAYOUT, type SearchListingPhotosOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, type SimilarByPhotoItem, type SimilarByPhotoResult, SimilarListingsResult, type SimilarPhotoMatch, Site, type StudioSdkContract, VISIT_TIME_ZONE, type VisitHours, type VisitLeadInput, type VisitSchedule, type VisitScheduleConfig, applyMatchedPhotoCover, coerceNpmVersion, collapseDuplicatedBrazilianMobileNine, compareSemver, composeSearchPublicHref, composeSearchPublicPath, createClient, createGaragemClient, defaultPhoneCountry, expandVisitSchedule, expandVisitTimeSlots, findPhoneCountry, formatAreaM2, formatGroupedInteger, formatListingPrice, formatPhoneNational, getLeadUi, getListingMarketPosition, getNeighborhoodSummary, getSimilarByPhoto, hasShowcaseLeadsPostUrl, isPhotoSearchOnPin, isStudioPreviewHost, isValidPhone, isVisitSlotAllowed, labelAmenities, listingAmenityGroups, listingBreadcrumb, listingBusinessLabel, listingDescriptionPreview, listingDetailFieldsModel, listingDetailModel, listingFacts, listingLocationBlock, listingLocationLabel, listingLookupKey, listingMapsHref, listingMediaOverlays, listingPhotoGroups, listingPublicPath, listingValues, listingVisualHighlights, marketExportsAvailableAt, marketPositionLabel, mergeAppliedSearchQueryIntoSearch, nationalPhoneDigits, normalizeVisitDate, normalizeVisitTime, parseAppliedSearchQuery, parseGroupedInteger, parsePhoneInput, parseReactSdkNamedImports, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, phoneCountrySearchValue, photoRoomLabel, photoSearchUrl, priceBandLabel, reduceAppliedSearchQuery, remaskPhoneForCountry, requestPriceEstimate, resolveMatchedCoverPhoto, resolvePublicSiteId, searchListingPhotos, serializeAppliedSearchQuery, slotsForDate, studioAmenityInstruction, studioChromeInstruction, studioCodegenContractViolations, studioDefaultLeadUi, studioLayoutInstruction, studioLeadInstruction, studioListingCardInstruction, studioListingDetailInstruction, studioMarketInstruction, studioPhotoInstruction, studioPhotoInstructionFor, studioPhotoSearchInstruction, studioPublishableKeyInstruction, studioSdkPinInstruction, studioSearchInstruction, studioSearchLandmarkInstruction, studioSiteWidthCss, submitContactLead, submitVisitLead, toE164, toListingCardModel, truncateNationalPhoneDigits, unavailableReactImports };
|