@garagem-ai/site-sdk 0.6.1 → 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/dist/index.d.mts CHANGED
@@ -1,151 +1,5 @@
1
- import { R as RequestNextOptions, L as ListingFilters, Q as QueryListingsParams, S as SearchListingsParams, C as CmsCollection, a as CmsEntriesResult, b as CmsEntry, c as ListingDetail, d as ListingsResult, e as SearchUi, f as SimilarListingsResult, g as Site, h as QueryListingsResult, i as SearchListingsResult, j as ListingLocation, k as ListingMedia, l as ListingBusinessType, m as ListingPriceVisibility, n as Listing, o as SearchPathFilters, p as SearchUiDictionary, q as QueryListingsFilters, A as AppliedSearchQuery, r as AppliedSearchChange } from './search-engine-CtnLzmwW.mjs';
2
- export { s as CmsEntryStatus, t as CmsFieldDefinition, u as CmsFieldType, v as CmsSeoData, F as FORBIDDEN_SEARCH_QUERY_KEYS, w as ListingPropertySummary, x as LocationNameTables, y as QueryListingsLocation, z as SEARCH_EMPTY_COPY, B as SEARCH_SORT_RELEVANCE, D as SearchChromeModel, E as SearchPathLocation, G as SearchUiFilter, H as SearchUiOption, T as TOOLBAR_PRIMARY_FILTER_IDS, I as applyPathFilter, J as buildQueryListingsParams, K as canonicalizeSearchHref, M as clearStagedPathFilters, N as countFacetChoices, O as countOptionLabel, P as displayPathLocation, U as hrefForAppliedChange, V as hrefForPathFilters, W as hrefWithExplicitPage, X as isListingDetailPath, Y as paginationPages, Z as pathFilterHasOption, _ as pathFilterValue, $ as publicSearchHref, a0 as rangeDraftFromPath, a1 as readPublicSearch, a2 as searchChromeModel, a3 as searchHrefUsesLegacyFilterQuery, a4 as searchResultsHeading, a5 as searchSortOptions, a6 as toolbarFilterIds, a7 as visibleSearchFilters } from './search-engine-CtnLzmwW.mjs';
3
-
4
- /** Custom fetch implementation. Defaults to the global `fetch`. */
5
- type FetchLike = typeof fetch;
6
- interface BaseOptions {
7
- /** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
8
- baseUrl?: string;
9
- /** Override the fetch implementation (testing, edge runtimes, retries). */
10
- fetch?: FetchLike;
11
- /**
12
- * Next.js App Router caching hints. Ignored on runtimes that don't
13
- * understand them.
14
- */
15
- next?: RequestNextOptions;
16
- }
17
- interface GetListingsOptions extends BaseOptions {
18
- siteId: string;
19
- filters?: ListingFilters;
20
- }
21
- interface GetListingOptions extends BaseOptions {
22
- siteId: string;
23
- listingId: string;
24
- }
25
- interface GetSiteOptions extends BaseOptions {
26
- /** Look up by site ID, or… */
27
- siteId?: string;
28
- /** …by domain. Exactly one of `siteId` / `domain` must be provided. */
29
- domain?: string;
30
- }
31
- interface SearchListingsOptions extends BaseOptions {
32
- siteId: string;
33
- params: SearchListingsParams;
34
- }
35
- interface GetSearchUiOptions extends BaseOptions {
36
- siteId: string;
37
- }
38
- interface QueryListingsOptions extends BaseOptions {
39
- siteId: string;
40
- params?: QueryListingsParams;
41
- }
42
- interface GetSimilarListingsOptions extends BaseOptions {
43
- siteId: string;
44
- listingId: string;
45
- /** Max similar cards to return (API default 6, cap 12). */
46
- limit?: number;
47
- }
48
- interface GetCmsCollectionsOptions extends BaseOptions {
49
- siteId: string;
50
- }
51
- interface GetCmsCollectionOptions extends BaseOptions {
52
- siteId: string;
53
- slug: string;
54
- }
55
- interface GetCmsEntriesOptions extends BaseOptions {
56
- siteId: string;
57
- collection: string;
58
- limit?: number;
59
- offset?: number;
60
- }
61
- interface GetCmsEntryOptions extends BaseOptions {
62
- siteId: string;
63
- collection: string;
64
- slug: string;
65
- }
66
- /** Error thrown when a fetcher hits a non-2xx response. */
67
- declare class GaragemSdkError extends Error {
68
- readonly status: number;
69
- readonly url: string;
70
- constructor(message: string, info: {
71
- status: number;
72
- url: string;
73
- });
74
- }
75
- /**
76
- * Fetch a paginated list of listings for a given site.
77
- *
78
- * @example
79
- * const { listings } = await getListings({
80
- * siteId: "abc",
81
- * filters: { city: "São Paulo", limit: 24 },
82
- * next: { revalidate: 300, tags: [`site:abc:listings`] },
83
- * });
84
- */
85
- declare function getListings(options: GetListingsOptions): Promise<ListingsResult>;
86
- /**
87
- * Fetch a single listing's full detail (amenities, gallery, building).
88
- * `listingId` accepts a code, UUID, or `id-{code}` URL segment.
89
- */
90
- declare function getListing(options: GetListingOptions): Promise<ListingDetail>;
91
- /**
92
- * Resolve a site's public profile by ID or by domain. Returns `null`
93
- * when the site does not exist or the host is unrecognized.
94
- *
95
- * @example
96
- * const site = await getSite({ domain: "imobiliariax.com.br" });
97
- * if (!site) return notFound();
98
- */
99
- declare function getSite(options: GetSiteOptions): Promise<Site | null>;
100
- /**
101
- * Advanced search escape hatch.
102
- *
103
- * Calls `POST /api/sites/{siteId}/search` directly and returns the raw
104
- * Typesense response (`{ found, page, hits: [{ document, ... }], ... }`).
105
- * Use when `queryListings` isn't expressive enough — faceted search,
106
- * multi-field sort, custom grouping, etc.
107
- *
108
- * @example
109
- * const result = await searchListings({
110
- * siteId: "abc",
111
- * params: {
112
- * q: "frente mar",
113
- * query_by: "title,description,neighborhood",
114
- * filter_by: "businessType:=sale && bedrooms:>=3",
115
- * sort_by: "price:asc",
116
- * per_page: 24,
117
- * page: 1,
118
- * facet_by: "neighborhood,propertyType",
119
- * },
120
- * });
121
- * for (const hit of result.hits) {
122
- * console.log(hit.document, hit.highlight);
123
- * }
124
- */
125
- declare function searchListings<TDocument = Record<string, unknown>>(options: SearchListingsOptions): Promise<SearchListingsResult<TDocument>>;
126
- /**
127
- * Tenant search schema: filters, slugs, sort tokens, defaultLimit 12.
128
- * Use this to render the search UI — do not hardcode property types.
129
- */
130
- declare function getSearchUi(options: GetSearchUiOptions): Promise<SearchUi>;
131
- /**
132
- * Friendly catalog search (editor combinators). Prefer this over
133
- * `searchListings` — that helper is a raw Typesense escape hatch.
134
- */
135
- declare function queryListings(options: QueryListingsOptions): Promise<QueryListingsResult>;
136
- /**
137
- * Fetch similar listings for a detail page carousel.
138
- * Returns an empty list when the reference listing is missing.
139
- */
140
- declare function getSimilarListings(options: GetSimilarListingsOptions): Promise<SimilarListingsResult>;
141
- /** List CMS collections for a site. */
142
- declare function getCmsCollections(options: GetCmsCollectionsOptions): Promise<CmsCollection[]>;
143
- /** Fetch one CMS collection schema by slug. */
144
- declare function getCmsCollection(options: GetCmsCollectionOptions): Promise<CmsCollection>;
145
- /** List published CMS entries for a collection. */
146
- declare function getCmsEntries(options: GetCmsEntriesOptions): Promise<CmsEntriesResult>;
147
- /** Fetch one published CMS entry by slug. */
148
- declare function getCmsEntry(options: GetCmsEntryOptions): Promise<CmsEntry>;
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';
149
3
 
150
4
  /**
151
5
  * Visit-lead schedule: hours in, slots out. Pure — no fetch, no React.
@@ -214,6 +68,8 @@ type GetLeadUiOptions = {
214
68
  baseUrl?: string;
215
69
  fetch?: FetchLike;
216
70
  next?: RequestNextOptions;
71
+ /** Site publishable key (`pk_live_…`). Not a secret. */
72
+ publishableKey?: string;
217
73
  };
218
74
  type LeadContact = {
219
75
  name: string;
@@ -225,6 +81,8 @@ type LeadSubmitBase = LeadContact & {
225
81
  siteId?: string | Promise<string>;
226
82
  baseUrl?: string;
227
83
  fetch?: FetchLike;
84
+ /** Site publishable key (`pk_live_…`). Not a secret. */
85
+ publishableKey?: string;
228
86
  listingId: string;
229
87
  /**
230
88
  * Active listing modality (`sale` | `rental` | `rent`). Always pass
@@ -248,11 +106,13 @@ type LeadSubmitResult = {
248
106
  status: 202;
249
107
  id: string;
250
108
  };
251
- 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";
252
110
  declare class LeadSubmitError extends Error {
253
111
  readonly code: LeadSubmitErrorCode;
254
112
  readonly status?: number;
255
113
  readonly retryAfterSeconds?: number;
114
+ /** Seconds to wait. Same value as `retryAfterSeconds`; `null` when unset. */
115
+ readonly retryAfter: number | null;
256
116
  constructor(message: string, info: {
257
117
  code: LeadSubmitErrorCode;
258
118
  status?: number;
@@ -588,6 +448,8 @@ interface ResolvePublicSiteIdOptions {
588
448
  fallback?: string | null;
589
449
  baseUrl?: string;
590
450
  fetch?: FetchLike;
451
+ /** Forwarded to `getSite` when the live host is resolved. */
452
+ publishableKey?: string;
591
453
  }
592
454
  declare function isStudioPreviewHost(host: string): boolean;
593
455
  /**
@@ -648,6 +510,24 @@ declare const STUDIO_SDK_CONTRACT: {
648
510
  */
649
511
  readonly unpublishedPhoneExports: readonly [];
650
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"];
651
531
  /**
652
532
  * Names already on the pinned npm tarball (`minNpmVersion`) — safe for
653
533
  * Studio prompts and completeness. Includes `visibleSearchFilters` +
@@ -662,8 +542,33 @@ declare const STUDIO_SDK_CONTRACT: {
662
542
  * already listed in `searchExports`.
663
543
  */
664
544
  readonly unpublishedSearchExports: readonly ["searchChromeModel", "rangeDraftFromPath"];
545
+ /**
546
+ * Market-data helpers (neighborhood price summary, listing market
547
+ * position, visitor price estimate, pt-BR labels). They ship in
548
+ * `marketExportsSince` and are prompt-safe only once `minNpmVersion`
549
+ * reaches that release; below it `studioCodegenContractViolations` flags
550
+ * the names and `studioMarketInstruction()` tells Studio not to generate
551
+ * the blocks at all. Every helper answers `available: false` unless the
552
+ * site's organization holds the IPTU module (`iptu_itbi_integration`)
553
+ * and the city is covered — generated sites render these blocks
554
+ * conditionally and never show cadastral or transaction data.
555
+ */
556
+ readonly marketExports: readonly ["getNeighborhoodSummary", "getListingMarketPosition", "requestPriceEstimate", "marketPositionLabel", "priceBandLabel"];
557
+ readonly marketExportsSince: "0.7.0";
558
+ /**
559
+ * Photo search ("busca pelo que as fotos mostram"): main-package helpers
560
+ * that ship together with the `/react` hook listed in
561
+ * `optionalReactExports` (`usePublicPhotoSearch`). Prompt-safe only once
562
+ * `minNpmVersion` reaches `photoSearchSince` — `studioPhotoSearchInstruction`
563
+ * and the Studio guidance print nothing before that, and
564
+ * `studioCodegenContractViolations` flags the names until then.
565
+ */
566
+ readonly photoSearchExports: readonly ["searchListingPhotos", "applyMatchedPhotoCover"];
567
+ readonly photoSearchSince: "0.7.0";
665
568
  };
666
569
  type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
570
+ /** Whether the pinned tarball carries the photo-search surface. */
571
+ declare function isPhotoSearchOnPin(pin?: string): boolean;
667
572
  /**
668
573
  * Global Studio content width. Mirrors Editor default `7xl` / `px-4`
669
574
  * without the Marca picker — v0 sites are not `@garagem/ui`.
@@ -688,12 +593,42 @@ declare function coerceNpmVersion(raw: unknown): string | null;
688
593
  declare function compareSemver(a: string, b: string): number;
689
594
  declare function parseReactSdkNamedImports(source: string): string[];
690
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;
691
604
  declare function studioSdkPinInstruction(): string;
692
605
  declare function studioLeadInstruction(): string;
693
606
  declare function studioListingCardInstruction(): string;
694
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;
695
616
  declare function studioAmenityInstruction(): string;
696
617
  declare function studioSearchInstruction(): string;
618
+ /** True when the pinned tarball ships the market-data helpers. */
619
+ declare function marketExportsAvailableAt(pin: string): boolean;
620
+ /**
621
+ * Market-data blocks (neighborhood price summary, listing market position,
622
+ * visitor price estimate). Names appear only when the pin ships them; below
623
+ * that pin the instruction carries no identifiers (v0 copies any it sees).
624
+ */
625
+ declare function studioMarketInstruction(pin?: string): string;
626
+ /**
627
+ * Photo search ("busca pelo que as fotos mostram") codegen instruction.
628
+ * Empty until the pinned tarball ships the surface (`photoSearchSince`), so
629
+ * no prompt names an identifier v0 cannot import.
630
+ */
631
+ declare function studioPhotoSearchInstruction(pin?: string): string;
697
632
  declare function studioChromeInstruction(): string;
698
633
  /**
699
634
  * Tokens that must not appear in Studio codegen (prompts, recipes, repair).
@@ -706,6 +641,12 @@ interface CreateGaragemClientOptions {
706
641
  baseUrl?: string;
707
642
  /** Pre-bind a site so each call doesn't repeat it. */
708
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;
709
650
  /** Custom fetch implementation. */
710
651
  fetch?: FetchLike;
711
652
  /** Default Next.js caching hints applied to every request. */
@@ -808,5 +749,402 @@ interface GaragemClient {
808
749
  * exported for the no-client style.
809
750
  */
810
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[];
878
+
879
+ /**
880
+ * Market-data types for the public site.
881
+ *
882
+ * IPTU-module requirement: every market endpoint answers
883
+ * `{ available: false, reason }` (HTTP 200) unless the site's organization
884
+ * holds the IPTU module (`iptu_itbi_integration`), the city is covered and
885
+ * the integration is configured. Render these blocks conditionally on
886
+ * `available`. The payloads carry only aggregates and the trimmed estimate —
887
+ * never comparables, transactions or cadastral identifiers.
888
+ */
889
+ /** Why a market helper answered `available: false`. */
890
+ type MarketUnavailableReason =
891
+ /** The organization does not hold the IPTU module (`iptu_itbi_integration`). */
892
+ "module_not_enabled"
893
+ /** Market-data integration is not configured for this environment. */
894
+ | "not_configured"
895
+ /** The site id does not resolve to an active site. */
896
+ | "site_not_found"
897
+ /** The city is outside the covered-city matrix. */
898
+ | "city_unsupported"
899
+ /** Only sale prices are covered. */
900
+ | "listing_type_unsupported"
901
+ /** Listing price is private or missing. */
902
+ | "price_unavailable"
903
+ /** No usable aggregate for the request. */
904
+ | "no_data"
905
+ /** The SDK was rate limited (HTTP 429); try again later. */
906
+ | "rate_limited";
907
+ type MarketPropertyType = "apartment" | "house";
908
+ type MarketListingType = "sale" | "rent";
909
+ interface NeighborhoodSummaryQuery {
910
+ /** City name or code (`"São Paulo"`, `"sp"`). */
911
+ city: string;
912
+ neighborhood: string;
913
+ /** Echoed back; the aggregate covers every property kind today. */
914
+ propertyType?: MarketPropertyType;
915
+ /** Defaults to `"sale"`; `"rent"` answers `listing_type_unsupported`. */
916
+ type?: MarketListingType;
917
+ }
918
+ interface NeighborhoodSummary {
919
+ available: boolean;
920
+ reason: MarketUnavailableReason | null;
921
+ /** Normalized city code (`sp` / `rj` / `bh`) when supported. */
922
+ city: string;
923
+ neighborhood: string;
924
+ propertyType: MarketPropertyType | null;
925
+ type: MarketListingType;
926
+ /** Lookback window in months. */
927
+ months: number;
928
+ /** Centavos per m². */
929
+ pricePerSqmCents: {
930
+ p25: number | null;
931
+ p50: number | null;
932
+ p75: number | null;
933
+ };
934
+ /** Pre-formatted `R$ X/m²` strings (`"—"` when missing). */
935
+ pricePerSqmFormatted: {
936
+ p25: string;
937
+ p50: string;
938
+ p75: string;
939
+ };
940
+ sampleSize: number | null;
941
+ /** pt-BR copy when unavailable. */
942
+ message: string | null;
943
+ }
944
+ /**
945
+ * Where a listing sits against the neighborhood quartiles:
946
+ * - `below_range`: under P25
947
+ * - `lower_range`: P25 ≤ price/m² < P50
948
+ * - `upper_range`: P50 ≤ price/m² ≤ P75
949
+ * - `above_range`: over P75
950
+ */
951
+ type MarketPriceBand = "below_range" | "lower_range" | "upper_range" | "above_range";
952
+ interface ListingMarketPosition {
953
+ available: boolean;
954
+ reason: MarketUnavailableReason | null;
955
+ listingId: string;
956
+ city: string | null;
957
+ neighborhood: string | null;
958
+ months: number;
959
+ /** Listing asking price per m², centavos. */
960
+ listingPricePerSqmCents: number | null;
961
+ listingPricePerSqmFormatted: string;
962
+ /** Neighborhood median (P50) price per m², centavos. */
963
+ medianPricePerSqmCents: number | null;
964
+ medianPricePerSqmFormatted: string;
965
+ /** Rounded percent vs the median; negative = below the median. */
966
+ percentVsMedian: number | null;
967
+ band: MarketPriceBand | null;
968
+ sampleSize: number | null;
969
+ message: string | null;
970
+ }
971
+ interface PriceEstimateInput {
972
+ /** City name or code (`"São Paulo"`, `"sp"`). */
973
+ city: string;
974
+ neighborhood?: string;
975
+ street?: string;
976
+ streetNumber?: string;
977
+ /** 8 digits, no dash. */
978
+ postalCode?: string;
979
+ /** m², 10–10000. */
980
+ areaSqm: number;
981
+ bedrooms?: number;
982
+ bathrooms?: number;
983
+ parkingSpots?: number;
984
+ propertyType?: MarketPropertyType;
985
+ listingType?: MarketListingType;
986
+ }
987
+ type PriceEstimateConfidence = "high" | "medium" | "low";
988
+ interface PriceEstimate {
989
+ available: boolean;
990
+ reason: MarketUnavailableReason | null;
991
+ city: string;
992
+ neighborhood: string | null;
993
+ estimatedPriceCents: number | null;
994
+ estimatedPriceFormatted: string;
995
+ rangeLowCents: number | null;
996
+ rangeHighCents: number | null;
997
+ rangeLowFormatted: string;
998
+ rangeHighFormatted: string;
999
+ confidenceLabel: PriceEstimateConfidence | null;
1000
+ sampleSize: number | null;
1001
+ /** pt-BR copy when unavailable. */
1002
+ message: string | null;
1003
+ }
1004
+
1005
+ /**
1006
+ * Market-data fetchers for the public site.
1007
+ *
1008
+ * Requires the IPTU module: every call answers `{ available: false, reason }`
1009
+ * unless the site's organization holds `iptu_itbi_integration`, the city
1010
+ * is covered and the integration is configured. Render nothing in that
1011
+ * case. A rate-limited call (HTTP 429) also comes back as
1012
+ * `available: false` with `reason: "rate_limited"` instead of throwing, so
1013
+ * a block can stay hidden without a try/catch; other non-2xx responses
1014
+ * throw `GaragemSdkError` like the rest of the SDK.
1015
+ */
1016
+
1017
+ interface MarketBaseOptions {
1018
+ /** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
1019
+ baseUrl?: string;
1020
+ /** Override the fetch implementation (testing, edge runtimes, retries). */
1021
+ fetch?: FetchLike;
1022
+ /** Next.js App Router caching hints. Ignored elsewhere. */
1023
+ next?: RequestNextOptions;
1024
+ }
1025
+ interface GetNeighborhoodSummaryOptions extends MarketBaseOptions {
1026
+ siteId: string;
1027
+ query: NeighborhoodSummaryQuery;
1028
+ }
1029
+ interface GetListingMarketPositionOptions extends MarketBaseOptions {
1030
+ siteId: string;
1031
+ /** Accepts a code, UUID, or `id-{code}` URL segment. */
1032
+ listingId: string;
1033
+ }
1034
+ interface RequestPriceEstimateOptions extends MarketBaseOptions {
1035
+ siteId: string;
1036
+ input: PriceEstimateInput;
1037
+ }
1038
+ /**
1039
+ * P25 / P50 / P75 price per m² and sample size for a neighborhood.
1040
+ *
1041
+ * @example
1042
+ * const summary = await getNeighborhoodSummary({
1043
+ * siteId,
1044
+ * query: { city: "São Paulo", neighborhood: "Moema" },
1045
+ * next: { revalidate: 900 },
1046
+ * });
1047
+ * if (summary.available) render(summary.pricePerSqmFormatted.p50);
1048
+ */
1049
+ declare function getNeighborhoodSummary(options: GetNeighborhoodSummaryOptions): Promise<NeighborhoodSummary>;
1050
+ /**
1051
+ * The listing's price per m² vs the neighborhood median, computed
1052
+ * server-side from the public listing and the neighborhood summary.
1053
+ *
1054
+ * @example
1055
+ * const position = await getListingMarketPosition({ siteId, listingId });
1056
+ * const label = marketPositionLabel(position); // "8% abaixo da mediana do bairro"
1057
+ */
1058
+ declare function getListingMarketPosition(options: GetListingMarketPositionOptions): Promise<ListingMarketPosition>;
1059
+ /**
1060
+ * Trimmed automated valuation (estimate, range, confidence) for
1061
+ * visitor-entered characteristics. Never returns comparables.
1062
+ *
1063
+ * Limited per IP and per site; a limited call answers
1064
+ * `reason: "rate_limited"`.
1065
+ *
1066
+ * @example
1067
+ * const estimate = await requestPriceEstimate({
1068
+ * siteId,
1069
+ * input: { city: "sp", neighborhood: "Moema", areaSqm: 80, bedrooms: 2 },
1070
+ * });
1071
+ */
1072
+ declare function requestPriceEstimate(options: RequestPriceEstimateOptions): Promise<PriceEstimate>;
1073
+
1074
+ /**
1075
+ * Headless pt-BR labels for the market-data blocks. Every helper returns
1076
+ * `null` when there is nothing to say (unavailable, missing numbers), so a
1077
+ * component can `label && <p>{label}</p>` without re-checking `available`.
1078
+ */
1079
+
1080
+ /**
1081
+ * "8% abaixo da mediana do bairro" / "12% acima da mediana do bairro" /
1082
+ * "Na mediana do bairro". `null` when the position is unavailable.
1083
+ */
1084
+ declare function marketPositionLabel(position: Pick<ListingMarketPosition, "available" | "percentVsMedian"> | null | undefined): string | null;
1085
+ /**
1086
+ * Quartile band copy. Accepts the band itself or a position; `null` when
1087
+ * the band is missing or the position is unavailable.
1088
+ */
1089
+ declare function priceBandLabel(input: MarketPriceBand | Pick<ListingMarketPosition, "available" | "band"> | null | undefined): string | null;
1090
+
1091
+ interface SearchListingPhotosOptions {
1092
+ /** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
1093
+ baseUrl?: string;
1094
+ /** Override the fetch implementation (testing, edge runtimes, retries). */
1095
+ fetch?: FetchLike;
1096
+ /** Next.js App Router caching hints. Ignored on other runtimes. */
1097
+ next?: RequestNextOptions;
1098
+ }
1099
+ /** Shortest query the API will embed; shorter text returns the empty result locally. */
1100
+ declare const PHOTO_SEARCH_MIN_QUERY_LENGTH = 3;
1101
+ /** Build the request URL (exported for tests and custom transports). */
1102
+ declare function photoSearchUrl(siteId: string, params: PhotoSearchParams, baseUrl?: string): string;
1103
+ /**
1104
+ * Search a site's listings by what their public photos show.
1105
+ *
1106
+ * Returns `{ available: false, items: [] }` (not an error) when the tenant
1107
+ * has not enabled photo search, so a site can hide the control. Queries
1108
+ * shorter than {@link PHOTO_SEARCH_MIN_QUERY_LENGTH} resolve locally to an
1109
+ * empty result without a request.
1110
+ *
1111
+ * @example
1112
+ * const result = await searchListingPhotos("abc", { q: "varanda gourmet" });
1113
+ * const cards = applyMatchedPhotoCover(
1114
+ * result.items.map((item) => item.listing),
1115
+ * result
1116
+ * );
1117
+ */
1118
+ declare function searchListingPhotos(siteId: string, params: PhotoSearchParams, options?: SearchListingPhotosOptions): Promise<PhotoSearchResult>;
1119
+
1120
+ /**
1121
+ * Largest vector distance a photo may have and still replace the cover.
1122
+ * Mirrors the CRM "Foto que combina com a busca" threshold
1123
+ * (`MATCHED_PHOTO_COVER_MAX_DISTANCE` in apps/foundation); keyword matches
1124
+ * (`distance: null`) are exact caption / room-type matches and always win.
1125
+ */
1126
+ declare const MATCHED_PHOTO_COVER_MAX_DISTANCE = 0.4;
1127
+ interface ApplyMatchedPhotoCoverOptions {
1128
+ /** Override {@link MATCHED_PHOTO_COVER_MAX_DISTANCE}. `Infinity` accepts every match. */
1129
+ maxDistance?: number;
1130
+ }
1131
+ /**
1132
+ * The photo that replaces a card cover, or `null` to keep the card's own
1133
+ * cover: keyword matches as-is, vector matches only within `maxDistance`.
1134
+ */
1135
+ declare function resolveMatchedCoverPhoto(photo: MatchedListingPhoto | null | undefined, maxDistance?: number): MatchedListingPhoto | null;
1136
+ /**
1137
+ * Headless mirror of the CRM cover switch: for every card whose listing has
1138
+ * a photo-search match, swap `coverImage` for the matched photo and attach
1139
+ * it as `matchedPhoto`. Cards without a match (or whose match is too far)
1140
+ * keep their cover with `matchedPhoto: null`. Order is preserved — pass
1141
+ * `result.items.map((item) => item.listing)` to render the photo-search
1142
+ * page nearest-first, or the regular search page to only swap covers.
1143
+ *
1144
+ * @example
1145
+ * const cards = applyMatchedPhotoCover(search.listings, photos.items);
1146
+ * cards.map((card) => <Card model={toListingCardModel(card)} badge={card.matchedPhoto} />)
1147
+ */
1148
+ declare function applyMatchedPhotoCover<T extends Listing>(cards: ReadonlyArray<T>, photoResults: PhotoSearchResult | ReadonlyArray<PhotoSearchItem> | null | undefined, options?: ApplyMatchedPhotoCoverOptions): Array<T & ListingWithMatchedPhoto>;
811
1149
 
812
- export { AMENITY_FALLBACK_LABELS, type AmenityLabelDictionary, type AmenityLabelOption, AppliedSearchChange, AppliedSearchQuery, CmsCollection, CmsEntriesResult, CmsEntry, type ContactLeadInput, type CreateGaragemClientOptions, DEFAULT_PHONE_COUNTRY_CODE, type FetchLike, type GaragemClient, GaragemSdkError, type GetCmsCollectionOptions, type GetCmsCollectionsOptions, type GetCmsEntriesOptions, type GetCmsEntryOptions, type GetLeadUiOptions, type GetListingOptions, type GetListingsOptions, type GetSearchUiOptions, type GetSimilarListingsOptions, type GetSiteOptions, 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, ListingMedia, type ListingMediaOverlay, ListingPriceVisibility, type ListingValue, ListingsResult, type LocationFilterInput, MAX_NATIONAL_PHONE_DIGITS, PHONE_COUNTRIES, type ParsedPhoneInput, type PhoneCountry, QueryListingsFilters, type QueryListingsOptions, QueryListingsParams, QueryListingsResult, RequestNextOptions, type ResolvePublicSiteIdOptions, STUDIO_DEFAULT_VISIT_SCHEDULE, STUDIO_SDK_CONTRACT, STUDIO_SDK_PACKAGE, STUDIO_SITE_LAYOUT, type SearchListingsOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, SimilarListingsResult, Site, type StudioSdkContract, VISIT_TIME_ZONE, type VisitHours, type VisitLeadInput, type VisitSchedule, type VisitScheduleConfig, coerceNpmVersion, collapseDuplicatedBrazilianMobileNine, compareSemver, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, defaultPhoneCountry, expandVisitSchedule, expandVisitTimeSlots, findPhoneCountry, formatAreaM2, formatGroupedInteger, formatListingPrice, formatPhoneNational, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getLeadUi, getListing, getListings, getSearchUi, getSimilarListings, getSite, hasShowcaseLeadsPostUrl, isStudioPreviewHost, isValidPhone, isVisitSlotAllowed, labelAmenities, listingAmenityGroups, listingBreadcrumb, listingBusinessLabel, listingDescriptionPreview, listingDetailFieldsModel, listingDetailModel, listingFacts, listingLocationBlock, listingLocationLabel, listingLookupKey, listingMapsHref, listingMediaOverlays, listingPublicPath, listingValues, mergeAppliedSearchQueryIntoSearch, nationalPhoneDigits, normalizeVisitDate, normalizeVisitTime, parseAppliedSearchQuery, parseGroupedInteger, parsePhoneInput, parseReactSdkNamedImports, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, phoneCountrySearchValue, queryListings, reduceAppliedSearchQuery, remaskPhoneForCountry, resolvePublicSiteId, searchListings, serializeAppliedSearchQuery, slotsForDate, studioAmenityInstruction, studioChromeInstruction, studioCodegenContractViolations, studioDefaultLeadUi, studioLayoutInstruction, studioLeadInstruction, studioListingCardInstruction, studioListingDetailInstruction, 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 };