@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 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 | 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
- | `getSearchUi({ siteId, next? })` | Tenant search schema (filters, slugs) |
68
- | `getLeadUi({ siteId, next? })` | Visit-default lead dialog schema (weekday hours, Sat/Sun flags) |
69
- | `submitVisitLead({ siteId, listingId, … })` | POST a visit lead (`listing.id` UUID; civil `visitDate` or `Date`/ISO instant normalized in the schedule timezone) |
70
- | `submitContactLead({ siteId, listingId, … })` | POST a contact lead (no date/time) |
71
- | `slotsForDate` / `normalizeVisitDate` / `expandVisitSchedule` | Pure schedule helpers (`America/Sao_Paulo`, default Mon–Fri 06:00–22:00) |
72
- | `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. |
73
- | `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. |
74
- | `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. |
75
- | `resolvePublicSiteId({ host?, fallback? })` | Preview uses `fallback` (`GARAGEM_SITE_ID`); live hosts resolve via `getSite({ domain })` |
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 | Description |
86
- | ------------------------------ | ----------------------------------------------------- |
87
- | `createGaragemClient(options)` | Pre-bind `baseUrl`, `siteId`, `fetch`, `next` |
88
- | `GaragemSdkError` | Thrown on non-2xx responses; carries `status` + `url` |
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
- ## Public keys & rate limiting (roadmap)
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
- Today every fetcher is anonymous. As the SDK approaches public launch we'll
296
- add **publishable keys** with per-tenant rate limits and a domain allowlist —
297
- no breaking changes to the call sites, just an additional `publishableKey`
298
- option on `createGaragemClient`.
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-OeONNDxl.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-OeONNDxl.mjs';
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 };