@garagem-ai/site-sdk 0.6.1 → 0.7.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 +91 -0
- package/dist/index.d.mts +313 -149
- package/dist/index.d.ts +313 -149
- package/dist/index.js +344 -4
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +329 -4
- package/dist/index.mjs.map +1 -1
- package/dist/react.d.mts +41 -2
- package/dist/react.d.ts +41 -2
- package/dist/react.js +194 -0
- package/dist/react.js.map +1 -1
- package/dist/react.mjs +192 -0
- package/dist/react.mjs.map +1 -1
- package/dist/{search-engine-CtnLzmwW.d.mts → types-photo-search-OeONNDxl.d.mts} +204 -1
- package/dist/{search-engine-CtnLzmwW.d.ts → types-photo-search-OeONNDxl.d.ts} +204 -1
- package/package.json +2 -1
- package/src/fetchers-market.ts +216 -0
- package/src/fetchers-photo-search.ts +101 -0
- package/src/index.ts +61 -0
- package/src/market-labels.ts +51 -0
- package/src/photo-search-cover.ts +90 -0
- package/src/react/index.ts +8 -0
- package/src/react/use-public-photo-search.ts +165 -0
- package/src/studio-contract.ts +104 -3
- package/src/types-market.ts +138 -0
- package/src/types-photo-search.ts +55 -0
- package/src/types.ts +7 -0
|
@@ -286,6 +286,13 @@ interface QueryListingsResult {
|
|
|
286
286
|
* This is the SDK's escape hatch when `queryListings` isn't expressive
|
|
287
287
|
* enough (faceted search, multi-field sort, custom grouping). It's an
|
|
288
288
|
* open dictionary on purpose; the only required field is `q`.
|
|
289
|
+
*
|
|
290
|
+
* The endpoint only forwards allowlisted query / filter / sort / pagination /
|
|
291
|
+
* facet / grouping / highlight params. Anything that would make Typesense
|
|
292
|
+
* call out (`vector_query`, `nl_query`, `conversation*`, `preset`,
|
|
293
|
+
* `remote_embedding_*`), curation overrides (`pinned_hits`, `hidden_hits`),
|
|
294
|
+
* `collection`, and embedding fields in `query_by` / `include_fields` are
|
|
295
|
+
* dropped server-side; `per_page` is capped at 250.
|
|
289
296
|
*/
|
|
290
297
|
interface SearchListingsParams {
|
|
291
298
|
q: string;
|
|
@@ -390,6 +397,152 @@ interface RequestNextOptions {
|
|
|
390
397
|
tags?: string[];
|
|
391
398
|
}
|
|
392
399
|
|
|
400
|
+
/** Custom fetch implementation. Defaults to the global `fetch`. */
|
|
401
|
+
type FetchLike = typeof fetch;
|
|
402
|
+
interface BaseOptions {
|
|
403
|
+
/** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
|
|
404
|
+
baseUrl?: string;
|
|
405
|
+
/** Override the fetch implementation (testing, edge runtimes, retries). */
|
|
406
|
+
fetch?: FetchLike;
|
|
407
|
+
/**
|
|
408
|
+
* Next.js App Router caching hints. Ignored on runtimes that don't
|
|
409
|
+
* understand them.
|
|
410
|
+
*/
|
|
411
|
+
next?: RequestNextOptions;
|
|
412
|
+
}
|
|
413
|
+
interface GetListingsOptions extends BaseOptions {
|
|
414
|
+
siteId: string;
|
|
415
|
+
filters?: ListingFilters;
|
|
416
|
+
}
|
|
417
|
+
interface GetListingOptions extends BaseOptions {
|
|
418
|
+
siteId: string;
|
|
419
|
+
listingId: string;
|
|
420
|
+
}
|
|
421
|
+
interface GetSiteOptions extends BaseOptions {
|
|
422
|
+
/** Look up by site ID, or… */
|
|
423
|
+
siteId?: string;
|
|
424
|
+
/** …by domain. Exactly one of `siteId` / `domain` must be provided. */
|
|
425
|
+
domain?: string;
|
|
426
|
+
}
|
|
427
|
+
interface SearchListingsOptions extends BaseOptions {
|
|
428
|
+
siteId: string;
|
|
429
|
+
params: SearchListingsParams;
|
|
430
|
+
}
|
|
431
|
+
interface GetSearchUiOptions extends BaseOptions {
|
|
432
|
+
siteId: string;
|
|
433
|
+
}
|
|
434
|
+
interface QueryListingsOptions extends BaseOptions {
|
|
435
|
+
siteId: string;
|
|
436
|
+
params?: QueryListingsParams;
|
|
437
|
+
}
|
|
438
|
+
interface GetSimilarListingsOptions extends BaseOptions {
|
|
439
|
+
siteId: string;
|
|
440
|
+
listingId: string;
|
|
441
|
+
/** Max similar cards to return (API default 6, cap 12). */
|
|
442
|
+
limit?: number;
|
|
443
|
+
}
|
|
444
|
+
interface GetCmsCollectionsOptions extends BaseOptions {
|
|
445
|
+
siteId: string;
|
|
446
|
+
}
|
|
447
|
+
interface GetCmsCollectionOptions extends BaseOptions {
|
|
448
|
+
siteId: string;
|
|
449
|
+
slug: string;
|
|
450
|
+
}
|
|
451
|
+
interface GetCmsEntriesOptions extends BaseOptions {
|
|
452
|
+
siteId: string;
|
|
453
|
+
collection: string;
|
|
454
|
+
limit?: number;
|
|
455
|
+
offset?: number;
|
|
456
|
+
}
|
|
457
|
+
interface GetCmsEntryOptions extends BaseOptions {
|
|
458
|
+
siteId: string;
|
|
459
|
+
collection: string;
|
|
460
|
+
slug: string;
|
|
461
|
+
}
|
|
462
|
+
/** Error thrown when a fetcher hits a non-2xx response. */
|
|
463
|
+
declare class GaragemSdkError extends Error {
|
|
464
|
+
readonly status: number;
|
|
465
|
+
readonly url: string;
|
|
466
|
+
constructor(message: string, info: {
|
|
467
|
+
status: number;
|
|
468
|
+
url: string;
|
|
469
|
+
});
|
|
470
|
+
}
|
|
471
|
+
/**
|
|
472
|
+
* Fetch a paginated list of listings for a given site.
|
|
473
|
+
*
|
|
474
|
+
* @example
|
|
475
|
+
* const { listings } = await getListings({
|
|
476
|
+
* siteId: "abc",
|
|
477
|
+
* filters: { city: "São Paulo", limit: 24 },
|
|
478
|
+
* next: { revalidate: 300, tags: [`site:abc:listings`] },
|
|
479
|
+
* });
|
|
480
|
+
*/
|
|
481
|
+
declare function getListings(options: GetListingsOptions): Promise<ListingsResult>;
|
|
482
|
+
/**
|
|
483
|
+
* Fetch a single listing's full detail (amenities, gallery, building).
|
|
484
|
+
* `listingId` accepts a code, UUID, or `id-{code}` URL segment.
|
|
485
|
+
*/
|
|
486
|
+
declare function getListing(options: GetListingOptions): Promise<ListingDetail>;
|
|
487
|
+
/**
|
|
488
|
+
* Resolve a site's public profile by ID or by domain. Returns `null`
|
|
489
|
+
* when the site does not exist or the host is unrecognized.
|
|
490
|
+
*
|
|
491
|
+
* @example
|
|
492
|
+
* const site = await getSite({ domain: "imobiliariax.com.br" });
|
|
493
|
+
* if (!site) return notFound();
|
|
494
|
+
*/
|
|
495
|
+
declare function getSite(options: GetSiteOptions): Promise<Site | null>;
|
|
496
|
+
/**
|
|
497
|
+
* Advanced search escape hatch.
|
|
498
|
+
*
|
|
499
|
+
* Calls `POST /api/sites/{siteId}/search` directly and returns the raw
|
|
500
|
+
* Typesense response (`{ found, page, hits: [{ document, ... }], ... }`).
|
|
501
|
+
* Use when `queryListings` isn't expressive enough — faceted search,
|
|
502
|
+
* multi-field sort, custom grouping, etc.
|
|
503
|
+
*
|
|
504
|
+
* @example
|
|
505
|
+
* const result = await searchListings({
|
|
506
|
+
* siteId: "abc",
|
|
507
|
+
* params: {
|
|
508
|
+
* q: "frente mar",
|
|
509
|
+
* query_by: "title,description,neighborhood",
|
|
510
|
+
* filter_by: "businessType:=sale && bedrooms:>=3",
|
|
511
|
+
* sort_by: "price:asc",
|
|
512
|
+
* per_page: 24,
|
|
513
|
+
* page: 1,
|
|
514
|
+
* facet_by: "neighborhood,propertyType",
|
|
515
|
+
* },
|
|
516
|
+
* });
|
|
517
|
+
* for (const hit of result.hits) {
|
|
518
|
+
* console.log(hit.document, hit.highlight);
|
|
519
|
+
* }
|
|
520
|
+
*/
|
|
521
|
+
declare function searchListings<TDocument = Record<string, unknown>>(options: SearchListingsOptions): Promise<SearchListingsResult<TDocument>>;
|
|
522
|
+
/**
|
|
523
|
+
* Tenant search schema: filters, slugs, sort tokens, defaultLimit 12.
|
|
524
|
+
* Use this to render the search UI — do not hardcode property types.
|
|
525
|
+
*/
|
|
526
|
+
declare function getSearchUi(options: GetSearchUiOptions): Promise<SearchUi>;
|
|
527
|
+
/**
|
|
528
|
+
* Friendly catalog search (editor combinators). Prefer this over
|
|
529
|
+
* `searchListings` — that helper is a raw Typesense escape hatch.
|
|
530
|
+
*/
|
|
531
|
+
declare function queryListings(options: QueryListingsOptions): Promise<QueryListingsResult>;
|
|
532
|
+
/**
|
|
533
|
+
* Fetch similar listings for a detail page carousel.
|
|
534
|
+
* Returns an empty list when the reference listing is missing.
|
|
535
|
+
*/
|
|
536
|
+
declare function getSimilarListings(options: GetSimilarListingsOptions): Promise<SimilarListingsResult>;
|
|
537
|
+
/** List CMS collections for a site. */
|
|
538
|
+
declare function getCmsCollections(options: GetCmsCollectionsOptions): Promise<CmsCollection[]>;
|
|
539
|
+
/** Fetch one CMS collection schema by slug. */
|
|
540
|
+
declare function getCmsCollection(options: GetCmsCollectionOptions): Promise<CmsCollection>;
|
|
541
|
+
/** List published CMS entries for a collection. */
|
|
542
|
+
declare function getCmsEntries(options: GetCmsEntriesOptions): Promise<CmsEntriesResult>;
|
|
543
|
+
/** Fetch one published CMS entry by slug. */
|
|
544
|
+
declare function getCmsEntry(options: GetCmsEntryOptions): Promise<CmsEntry>;
|
|
545
|
+
|
|
393
546
|
/** Query keys that must never encode filters (Editor/Studio path contract). */
|
|
394
547
|
declare const FORBIDDEN_SEARCH_QUERY_KEYS: readonly ["tipo", "quartos", "tipo-imovel", "banheiros", "vagas"];
|
|
395
548
|
/** Default option: omit `ordenar` (API has no relevance token). */
|
|
@@ -471,4 +624,54 @@ type SearchChromeModel = {
|
|
|
471
624
|
};
|
|
472
625
|
declare function searchChromeModel(schema: SearchUi | null, pathFilters: SearchPathFilters, locationNames?: LocationNameTables | null): SearchChromeModel;
|
|
473
626
|
|
|
474
|
-
|
|
627
|
+
/**
|
|
628
|
+
* "Busca pelo que as fotos mostram": search a site's catalog by what the
|
|
629
|
+
* public photos show (`GET /api/sites/{siteId}/search/photos`).
|
|
630
|
+
*/
|
|
631
|
+
interface PhotoSearchParams {
|
|
632
|
+
/** Free text describing the photo ("varanda gourmet com churrasqueira"). */
|
|
633
|
+
q: string;
|
|
634
|
+
/** Listings per page (API default 12, cap 24). */
|
|
635
|
+
limit?: number;
|
|
636
|
+
/** 1-based page inside the API's candidate window. */
|
|
637
|
+
page?: number;
|
|
638
|
+
}
|
|
639
|
+
/** The photo that matched the words, chosen the same way as the CRM cover switch. */
|
|
640
|
+
interface MatchedListingPhoto {
|
|
641
|
+
/** Media id; stable across listings that share the same photo. */
|
|
642
|
+
id: string;
|
|
643
|
+
src: string;
|
|
644
|
+
alt: string;
|
|
645
|
+
caption: string | null;
|
|
646
|
+
/**
|
|
647
|
+
* Vector distance for a visual match (lower is closer). `null` when the
|
|
648
|
+
* photo matched through its caption / room type instead (an exact text
|
|
649
|
+
* match, accepted as-is by {@link applyMatchedPhotoCover}).
|
|
650
|
+
*/
|
|
651
|
+
distance: number | null;
|
|
652
|
+
}
|
|
653
|
+
interface PhotoSearchItem {
|
|
654
|
+
/** Same card shape as `getListings` / `queryListings`. */
|
|
655
|
+
listing: Listing;
|
|
656
|
+
matchedPhoto: MatchedListingPhoto;
|
|
657
|
+
/** Lane score; higher is closer. Items arrive nearest-first. */
|
|
658
|
+
score: number;
|
|
659
|
+
}
|
|
660
|
+
interface PhotoSearchResult {
|
|
661
|
+
/**
|
|
662
|
+
* `false` when the tenant has not enabled photo search: `items` is empty
|
|
663
|
+
* and the site should hide the feature rather than show "no results".
|
|
664
|
+
*/
|
|
665
|
+
available: boolean;
|
|
666
|
+
items: PhotoSearchItem[];
|
|
667
|
+
/** Matching listings across every page (bounded by the API candidate window). */
|
|
668
|
+
total: number;
|
|
669
|
+
page: number;
|
|
670
|
+
limit: number;
|
|
671
|
+
}
|
|
672
|
+
/** A listing card whose cover was swapped for the photo that matched the search. */
|
|
673
|
+
type ListingWithMatchedPhoto = Listing & {
|
|
674
|
+
matchedPhoto: MatchedListingPhoto | null;
|
|
675
|
+
};
|
|
676
|
+
|
|
677
|
+
export { type SearchPathLocation as $, type AppliedSearchQuery as A, type GetCmsCollectionOptions as B, type CmsCollection as C, type GetCmsCollectionsOptions as D, type GetCmsEntriesOptions as E, type FetchLike as F, GaragemSdkError as G, type GetCmsEntryOptions as H, type GetListingOptions as I, type GetListingsOptions as J, type GetSearchUiOptions as K, type ListingDetail as L, type MatchedListingPhoto as M, type GetSimilarListingsOptions as N, type GetSiteOptions as O, type PhotoSearchParams as P, type QueryListingsFilters as Q, type RequestNextOptions as R, type SearchPathFilters as S, type ListingPropertySummary as T, type LocationNameTables as U, type QueryListingsLocation as V, type QueryListingsOptions as W, SEARCH_EMPTY_COPY as X, SEARCH_SORT_RELEVANCE as Y, type SearchChromeModel as Z, type SearchListingsOptions as _, type ListingLocation as a, type SearchUiFilter as a0, type SearchUiOption as a1, TOOLBAR_PRIMARY_FILTER_IDS as a2, applyPathFilter as a3, buildQueryListingsParams as a4, canonicalizeSearchHref as a5, clearStagedPathFilters as a6, countFacetChoices as a7, countOptionLabel as a8, displayPathLocation as a9, visibleSearchFilters as aA, getCmsCollection as aa, getCmsCollections as ab, getCmsEntries as ac, getCmsEntry as ad, getListing as ae, getListings as af, getSearchUi as ag, getSimilarListings as ah, getSite as ai, hrefForAppliedChange as aj, hrefForPathFilters as ak, hrefWithExplicitPage as al, isListingDetailPath as am, paginationPages as an, pathFilterHasOption as ao, pathFilterValue as ap, publicSearchHref as aq, queryListings as ar, rangeDraftFromPath as as, readPublicSearch as at, searchChromeModel as au, searchHrefUsesLegacyFilterQuery as av, searchListings as aw, searchResultsHeading as ax, searchSortOptions as ay, toolbarFilterIds as az, type ListingMedia as b, type ListingBusinessType as c, type ListingPriceVisibility as d, type Listing as e, type SearchUiDictionary as f, type AppliedSearchChange as g, type ListingFilters as h, type ListingsResult as i, type Site as j, type SearchListingsParams as k, type SearchListingsResult as l, type SearchUi as m, type QueryListingsParams as n, type QueryListingsResult as o, type SimilarListingsResult as p, type CmsEntriesResult as q, type CmsEntry as r, type PhotoSearchResult as s, type PhotoSearchItem as t, type ListingWithMatchedPhoto as u, type CmsEntryStatus as v, type CmsFieldDefinition as w, type CmsFieldType as x, type CmsSeoData as y, FORBIDDEN_SEARCH_QUERY_KEYS as z };
|
|
@@ -286,6 +286,13 @@ interface QueryListingsResult {
|
|
|
286
286
|
* This is the SDK's escape hatch when `queryListings` isn't expressive
|
|
287
287
|
* enough (faceted search, multi-field sort, custom grouping). It's an
|
|
288
288
|
* open dictionary on purpose; the only required field is `q`.
|
|
289
|
+
*
|
|
290
|
+
* The endpoint only forwards allowlisted query / filter / sort / pagination /
|
|
291
|
+
* facet / grouping / highlight params. Anything that would make Typesense
|
|
292
|
+
* call out (`vector_query`, `nl_query`, `conversation*`, `preset`,
|
|
293
|
+
* `remote_embedding_*`), curation overrides (`pinned_hits`, `hidden_hits`),
|
|
294
|
+
* `collection`, and embedding fields in `query_by` / `include_fields` are
|
|
295
|
+
* dropped server-side; `per_page` is capped at 250.
|
|
289
296
|
*/
|
|
290
297
|
interface SearchListingsParams {
|
|
291
298
|
q: string;
|
|
@@ -390,6 +397,152 @@ interface RequestNextOptions {
|
|
|
390
397
|
tags?: string[];
|
|
391
398
|
}
|
|
392
399
|
|
|
400
|
+
/** Custom fetch implementation. Defaults to the global `fetch`. */
|
|
401
|
+
type FetchLike = typeof fetch;
|
|
402
|
+
interface BaseOptions {
|
|
403
|
+
/** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
|
|
404
|
+
baseUrl?: string;
|
|
405
|
+
/** Override the fetch implementation (testing, edge runtimes, retries). */
|
|
406
|
+
fetch?: FetchLike;
|
|
407
|
+
/**
|
|
408
|
+
* Next.js App Router caching hints. Ignored on runtimes that don't
|
|
409
|
+
* understand them.
|
|
410
|
+
*/
|
|
411
|
+
next?: RequestNextOptions;
|
|
412
|
+
}
|
|
413
|
+
interface GetListingsOptions extends BaseOptions {
|
|
414
|
+
siteId: string;
|
|
415
|
+
filters?: ListingFilters;
|
|
416
|
+
}
|
|
417
|
+
interface GetListingOptions extends BaseOptions {
|
|
418
|
+
siteId: string;
|
|
419
|
+
listingId: string;
|
|
420
|
+
}
|
|
421
|
+
interface GetSiteOptions extends BaseOptions {
|
|
422
|
+
/** Look up by site ID, or… */
|
|
423
|
+
siteId?: string;
|
|
424
|
+
/** …by domain. Exactly one of `siteId` / `domain` must be provided. */
|
|
425
|
+
domain?: string;
|
|
426
|
+
}
|
|
427
|
+
interface SearchListingsOptions extends BaseOptions {
|
|
428
|
+
siteId: string;
|
|
429
|
+
params: SearchListingsParams;
|
|
430
|
+
}
|
|
431
|
+
interface GetSearchUiOptions extends BaseOptions {
|
|
432
|
+
siteId: string;
|
|
433
|
+
}
|
|
434
|
+
interface QueryListingsOptions extends BaseOptions {
|
|
435
|
+
siteId: string;
|
|
436
|
+
params?: QueryListingsParams;
|
|
437
|
+
}
|
|
438
|
+
interface GetSimilarListingsOptions extends BaseOptions {
|
|
439
|
+
siteId: string;
|
|
440
|
+
listingId: string;
|
|
441
|
+
/** Max similar cards to return (API default 6, cap 12). */
|
|
442
|
+
limit?: number;
|
|
443
|
+
}
|
|
444
|
+
interface GetCmsCollectionsOptions extends BaseOptions {
|
|
445
|
+
siteId: string;
|
|
446
|
+
}
|
|
447
|
+
interface GetCmsCollectionOptions extends BaseOptions {
|
|
448
|
+
siteId: string;
|
|
449
|
+
slug: string;
|
|
450
|
+
}
|
|
451
|
+
interface GetCmsEntriesOptions extends BaseOptions {
|
|
452
|
+
siteId: string;
|
|
453
|
+
collection: string;
|
|
454
|
+
limit?: number;
|
|
455
|
+
offset?: number;
|
|
456
|
+
}
|
|
457
|
+
interface GetCmsEntryOptions extends BaseOptions {
|
|
458
|
+
siteId: string;
|
|
459
|
+
collection: string;
|
|
460
|
+
slug: string;
|
|
461
|
+
}
|
|
462
|
+
/** Error thrown when a fetcher hits a non-2xx response. */
|
|
463
|
+
declare class GaragemSdkError extends Error {
|
|
464
|
+
readonly status: number;
|
|
465
|
+
readonly url: string;
|
|
466
|
+
constructor(message: string, info: {
|
|
467
|
+
status: number;
|
|
468
|
+
url: string;
|
|
469
|
+
});
|
|
470
|
+
}
|
|
471
|
+
/**
|
|
472
|
+
* Fetch a paginated list of listings for a given site.
|
|
473
|
+
*
|
|
474
|
+
* @example
|
|
475
|
+
* const { listings } = await getListings({
|
|
476
|
+
* siteId: "abc",
|
|
477
|
+
* filters: { city: "São Paulo", limit: 24 },
|
|
478
|
+
* next: { revalidate: 300, tags: [`site:abc:listings`] },
|
|
479
|
+
* });
|
|
480
|
+
*/
|
|
481
|
+
declare function getListings(options: GetListingsOptions): Promise<ListingsResult>;
|
|
482
|
+
/**
|
|
483
|
+
* Fetch a single listing's full detail (amenities, gallery, building).
|
|
484
|
+
* `listingId` accepts a code, UUID, or `id-{code}` URL segment.
|
|
485
|
+
*/
|
|
486
|
+
declare function getListing(options: GetListingOptions): Promise<ListingDetail>;
|
|
487
|
+
/**
|
|
488
|
+
* Resolve a site's public profile by ID or by domain. Returns `null`
|
|
489
|
+
* when the site does not exist or the host is unrecognized.
|
|
490
|
+
*
|
|
491
|
+
* @example
|
|
492
|
+
* const site = await getSite({ domain: "imobiliariax.com.br" });
|
|
493
|
+
* if (!site) return notFound();
|
|
494
|
+
*/
|
|
495
|
+
declare function getSite(options: GetSiteOptions): Promise<Site | null>;
|
|
496
|
+
/**
|
|
497
|
+
* Advanced search escape hatch.
|
|
498
|
+
*
|
|
499
|
+
* Calls `POST /api/sites/{siteId}/search` directly and returns the raw
|
|
500
|
+
* Typesense response (`{ found, page, hits: [{ document, ... }], ... }`).
|
|
501
|
+
* Use when `queryListings` isn't expressive enough — faceted search,
|
|
502
|
+
* multi-field sort, custom grouping, etc.
|
|
503
|
+
*
|
|
504
|
+
* @example
|
|
505
|
+
* const result = await searchListings({
|
|
506
|
+
* siteId: "abc",
|
|
507
|
+
* params: {
|
|
508
|
+
* q: "frente mar",
|
|
509
|
+
* query_by: "title,description,neighborhood",
|
|
510
|
+
* filter_by: "businessType:=sale && bedrooms:>=3",
|
|
511
|
+
* sort_by: "price:asc",
|
|
512
|
+
* per_page: 24,
|
|
513
|
+
* page: 1,
|
|
514
|
+
* facet_by: "neighborhood,propertyType",
|
|
515
|
+
* },
|
|
516
|
+
* });
|
|
517
|
+
* for (const hit of result.hits) {
|
|
518
|
+
* console.log(hit.document, hit.highlight);
|
|
519
|
+
* }
|
|
520
|
+
*/
|
|
521
|
+
declare function searchListings<TDocument = Record<string, unknown>>(options: SearchListingsOptions): Promise<SearchListingsResult<TDocument>>;
|
|
522
|
+
/**
|
|
523
|
+
* Tenant search schema: filters, slugs, sort tokens, defaultLimit 12.
|
|
524
|
+
* Use this to render the search UI — do not hardcode property types.
|
|
525
|
+
*/
|
|
526
|
+
declare function getSearchUi(options: GetSearchUiOptions): Promise<SearchUi>;
|
|
527
|
+
/**
|
|
528
|
+
* Friendly catalog search (editor combinators). Prefer this over
|
|
529
|
+
* `searchListings` — that helper is a raw Typesense escape hatch.
|
|
530
|
+
*/
|
|
531
|
+
declare function queryListings(options: QueryListingsOptions): Promise<QueryListingsResult>;
|
|
532
|
+
/**
|
|
533
|
+
* Fetch similar listings for a detail page carousel.
|
|
534
|
+
* Returns an empty list when the reference listing is missing.
|
|
535
|
+
*/
|
|
536
|
+
declare function getSimilarListings(options: GetSimilarListingsOptions): Promise<SimilarListingsResult>;
|
|
537
|
+
/** List CMS collections for a site. */
|
|
538
|
+
declare function getCmsCollections(options: GetCmsCollectionsOptions): Promise<CmsCollection[]>;
|
|
539
|
+
/** Fetch one CMS collection schema by slug. */
|
|
540
|
+
declare function getCmsCollection(options: GetCmsCollectionOptions): Promise<CmsCollection>;
|
|
541
|
+
/** List published CMS entries for a collection. */
|
|
542
|
+
declare function getCmsEntries(options: GetCmsEntriesOptions): Promise<CmsEntriesResult>;
|
|
543
|
+
/** Fetch one published CMS entry by slug. */
|
|
544
|
+
declare function getCmsEntry(options: GetCmsEntryOptions): Promise<CmsEntry>;
|
|
545
|
+
|
|
393
546
|
/** Query keys that must never encode filters (Editor/Studio path contract). */
|
|
394
547
|
declare const FORBIDDEN_SEARCH_QUERY_KEYS: readonly ["tipo", "quartos", "tipo-imovel", "banheiros", "vagas"];
|
|
395
548
|
/** Default option: omit `ordenar` (API has no relevance token). */
|
|
@@ -471,4 +624,54 @@ type SearchChromeModel = {
|
|
|
471
624
|
};
|
|
472
625
|
declare function searchChromeModel(schema: SearchUi | null, pathFilters: SearchPathFilters, locationNames?: LocationNameTables | null): SearchChromeModel;
|
|
473
626
|
|
|
474
|
-
|
|
627
|
+
/**
|
|
628
|
+
* "Busca pelo que as fotos mostram": search a site's catalog by what the
|
|
629
|
+
* public photos show (`GET /api/sites/{siteId}/search/photos`).
|
|
630
|
+
*/
|
|
631
|
+
interface PhotoSearchParams {
|
|
632
|
+
/** Free text describing the photo ("varanda gourmet com churrasqueira"). */
|
|
633
|
+
q: string;
|
|
634
|
+
/** Listings per page (API default 12, cap 24). */
|
|
635
|
+
limit?: number;
|
|
636
|
+
/** 1-based page inside the API's candidate window. */
|
|
637
|
+
page?: number;
|
|
638
|
+
}
|
|
639
|
+
/** The photo that matched the words, chosen the same way as the CRM cover switch. */
|
|
640
|
+
interface MatchedListingPhoto {
|
|
641
|
+
/** Media id; stable across listings that share the same photo. */
|
|
642
|
+
id: string;
|
|
643
|
+
src: string;
|
|
644
|
+
alt: string;
|
|
645
|
+
caption: string | null;
|
|
646
|
+
/**
|
|
647
|
+
* Vector distance for a visual match (lower is closer). `null` when the
|
|
648
|
+
* photo matched through its caption / room type instead (an exact text
|
|
649
|
+
* match, accepted as-is by {@link applyMatchedPhotoCover}).
|
|
650
|
+
*/
|
|
651
|
+
distance: number | null;
|
|
652
|
+
}
|
|
653
|
+
interface PhotoSearchItem {
|
|
654
|
+
/** Same card shape as `getListings` / `queryListings`. */
|
|
655
|
+
listing: Listing;
|
|
656
|
+
matchedPhoto: MatchedListingPhoto;
|
|
657
|
+
/** Lane score; higher is closer. Items arrive nearest-first. */
|
|
658
|
+
score: number;
|
|
659
|
+
}
|
|
660
|
+
interface PhotoSearchResult {
|
|
661
|
+
/**
|
|
662
|
+
* `false` when the tenant has not enabled photo search: `items` is empty
|
|
663
|
+
* and the site should hide the feature rather than show "no results".
|
|
664
|
+
*/
|
|
665
|
+
available: boolean;
|
|
666
|
+
items: PhotoSearchItem[];
|
|
667
|
+
/** Matching listings across every page (bounded by the API candidate window). */
|
|
668
|
+
total: number;
|
|
669
|
+
page: number;
|
|
670
|
+
limit: number;
|
|
671
|
+
}
|
|
672
|
+
/** A listing card whose cover was swapped for the photo that matched the search. */
|
|
673
|
+
type ListingWithMatchedPhoto = Listing & {
|
|
674
|
+
matchedPhoto: MatchedListingPhoto | null;
|
|
675
|
+
};
|
|
676
|
+
|
|
677
|
+
export { type SearchPathLocation as $, type AppliedSearchQuery as A, type GetCmsCollectionOptions as B, type CmsCollection as C, type GetCmsCollectionsOptions as D, type GetCmsEntriesOptions as E, type FetchLike as F, GaragemSdkError as G, type GetCmsEntryOptions as H, type GetListingOptions as I, type GetListingsOptions as J, type GetSearchUiOptions as K, type ListingDetail as L, type MatchedListingPhoto as M, type GetSimilarListingsOptions as N, type GetSiteOptions as O, type PhotoSearchParams as P, type QueryListingsFilters as Q, type RequestNextOptions as R, type SearchPathFilters as S, type ListingPropertySummary as T, type LocationNameTables as U, type QueryListingsLocation as V, type QueryListingsOptions as W, SEARCH_EMPTY_COPY as X, SEARCH_SORT_RELEVANCE as Y, type SearchChromeModel as Z, type SearchListingsOptions as _, type ListingLocation as a, type SearchUiFilter as a0, type SearchUiOption as a1, TOOLBAR_PRIMARY_FILTER_IDS as a2, applyPathFilter as a3, buildQueryListingsParams as a4, canonicalizeSearchHref as a5, clearStagedPathFilters as a6, countFacetChoices as a7, countOptionLabel as a8, displayPathLocation as a9, visibleSearchFilters as aA, getCmsCollection as aa, getCmsCollections as ab, getCmsEntries as ac, getCmsEntry as ad, getListing as ae, getListings as af, getSearchUi as ag, getSimilarListings as ah, getSite as ai, hrefForAppliedChange as aj, hrefForPathFilters as ak, hrefWithExplicitPage as al, isListingDetailPath as am, paginationPages as an, pathFilterHasOption as ao, pathFilterValue as ap, publicSearchHref as aq, queryListings as ar, rangeDraftFromPath as as, readPublicSearch as at, searchChromeModel as au, searchHrefUsesLegacyFilterQuery as av, searchListings as aw, searchResultsHeading as ax, searchSortOptions as ay, toolbarFilterIds as az, type ListingMedia as b, type ListingBusinessType as c, type ListingPriceVisibility as d, type Listing as e, type SearchUiDictionary as f, type AppliedSearchChange as g, type ListingFilters as h, type ListingsResult as i, type Site as j, type SearchListingsParams as k, type SearchListingsResult as l, type SearchUi as m, type QueryListingsParams as n, type QueryListingsResult as o, type SimilarListingsResult as p, type CmsEntriesResult as q, type CmsEntry as r, type PhotoSearchResult as s, type PhotoSearchItem as t, type ListingWithMatchedPhoto as u, type CmsEntryStatus as v, type CmsFieldDefinition as w, type CmsFieldType as x, type CmsSeoData as y, FORBIDDEN_SEARCH_QUERY_KEYS as z };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@garagem-ai/site-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Typed, runtime-agnostic SDK for building custom real estate sites against the Garagem platform. Drop into any Next.js (or other JS) project to fetch listings, sites and CMS data.",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -57,6 +57,7 @@
|
|
|
57
57
|
"@types/node": "^20.10.8",
|
|
58
58
|
"@types/react": "19.1.4",
|
|
59
59
|
"eslint": "^9.0.0",
|
|
60
|
+
"jsdom": "^26.1.0",
|
|
60
61
|
"next": "16.4.0-canary.15",
|
|
61
62
|
"react": "19.2.1",
|
|
62
63
|
"react-dom": "19.2.1",
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Market-data fetchers for the public site.
|
|
3
|
+
*
|
|
4
|
+
* Requires the IPTU module: every call answers `{ available: false, reason }`
|
|
5
|
+
* unless the site's organization holds `iptu_itbi_integration`, the city
|
|
6
|
+
* is covered and the integration is configured. Render nothing in that
|
|
7
|
+
* case. A rate-limited call (HTTP 429) also comes back as
|
|
8
|
+
* `available: false` with `reason: "rate_limited"` instead of throwing, so
|
|
9
|
+
* a block can stay hidden without a try/catch; other non-2xx responses
|
|
10
|
+
* throw `GaragemSdkError` like the rest of the SDK.
|
|
11
|
+
*/
|
|
12
|
+
import { GaragemSdkError, callJson, type FetchLike } from "./fetchers";
|
|
13
|
+
import { listingLookupKey } from "./listing-path";
|
|
14
|
+
import { coerceSiteId, normalizeBaseUrl } from "./internal/url";
|
|
15
|
+
import type { RequestNextOptions } from "./types";
|
|
16
|
+
import type {
|
|
17
|
+
ListingMarketPosition,
|
|
18
|
+
NeighborhoodSummary,
|
|
19
|
+
NeighborhoodSummaryQuery,
|
|
20
|
+
PriceEstimate,
|
|
21
|
+
PriceEstimateInput,
|
|
22
|
+
} from "./types-market";
|
|
23
|
+
|
|
24
|
+
interface MarketBaseOptions {
|
|
25
|
+
/** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
|
|
26
|
+
baseUrl?: string;
|
|
27
|
+
/** Override the fetch implementation (testing, edge runtimes, retries). */
|
|
28
|
+
fetch?: FetchLike;
|
|
29
|
+
/** Next.js App Router caching hints. Ignored elsewhere. */
|
|
30
|
+
next?: RequestNextOptions;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export interface GetNeighborhoodSummaryOptions extends MarketBaseOptions {
|
|
34
|
+
siteId: string;
|
|
35
|
+
query: NeighborhoodSummaryQuery;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export interface GetListingMarketPositionOptions extends MarketBaseOptions {
|
|
39
|
+
siteId: string;
|
|
40
|
+
/** Accepts a code, UUID, or `id-{code}` URL segment. */
|
|
41
|
+
listingId: string;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
export interface RequestPriceEstimateOptions extends MarketBaseOptions {
|
|
45
|
+
siteId: string;
|
|
46
|
+
input: PriceEstimateInput;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
const RATE_LIMITED_MESSAGE =
|
|
50
|
+
"Muitas consultas em pouco tempo. Tente novamente em instantes.";
|
|
51
|
+
|
|
52
|
+
function isRateLimited(error: unknown): boolean {
|
|
53
|
+
return error instanceof GaragemSdkError && error.status === 429;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* P25 / P50 / P75 price per m² and sample size for a neighborhood.
|
|
58
|
+
*
|
|
59
|
+
* @example
|
|
60
|
+
* const summary = await getNeighborhoodSummary({
|
|
61
|
+
* siteId,
|
|
62
|
+
* query: { city: "São Paulo", neighborhood: "Moema" },
|
|
63
|
+
* next: { revalidate: 900 },
|
|
64
|
+
* });
|
|
65
|
+
* if (summary.available) render(summary.pricePerSqmFormatted.p50);
|
|
66
|
+
*/
|
|
67
|
+
export async function getNeighborhoodSummary(
|
|
68
|
+
options: GetNeighborhoodSummaryOptions
|
|
69
|
+
): Promise<NeighborhoodSummary> {
|
|
70
|
+
const { query, baseUrl, fetch: fetchImpl, next } = options;
|
|
71
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
72
|
+
if (!query?.city?.trim() || !query?.neighborhood?.trim()) {
|
|
73
|
+
throw new TypeError(
|
|
74
|
+
"getNeighborhoodSummary: `query.city` and `query.neighborhood` are required"
|
|
75
|
+
);
|
|
76
|
+
}
|
|
77
|
+
const base = normalizeBaseUrl(baseUrl);
|
|
78
|
+
const params = new URLSearchParams();
|
|
79
|
+
params.set("city", query.city.trim());
|
|
80
|
+
params.set("neighborhood", query.neighborhood.trim());
|
|
81
|
+
if (query.propertyType) params.set("propertyType", query.propertyType);
|
|
82
|
+
if (query.type) params.set("type", query.type);
|
|
83
|
+
const url = `${base}/api/sites/${encodeURIComponent(siteId)}/market/neighborhood-summary?${params.toString()}`;
|
|
84
|
+
|
|
85
|
+
try {
|
|
86
|
+
return await callJson<NeighborhoodSummary>(
|
|
87
|
+
url,
|
|
88
|
+
{ method: "GET", headers: { Accept: "application/json" }, next },
|
|
89
|
+
fetchImpl ?? fetch
|
|
90
|
+
);
|
|
91
|
+
} catch (error) {
|
|
92
|
+
if (!isRateLimited(error)) throw error;
|
|
93
|
+
return {
|
|
94
|
+
available: false,
|
|
95
|
+
reason: "rate_limited",
|
|
96
|
+
city: query.city,
|
|
97
|
+
neighborhood: query.neighborhood,
|
|
98
|
+
propertyType: query.propertyType ?? null,
|
|
99
|
+
type: query.type ?? "sale",
|
|
100
|
+
months: 12,
|
|
101
|
+
pricePerSqmCents: { p25: null, p50: null, p75: null },
|
|
102
|
+
pricePerSqmFormatted: { p25: "—", p50: "—", p75: "—" },
|
|
103
|
+
sampleSize: null,
|
|
104
|
+
message: RATE_LIMITED_MESSAGE,
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* The listing's price per m² vs the neighborhood median, computed
|
|
111
|
+
* server-side from the public listing and the neighborhood summary.
|
|
112
|
+
*
|
|
113
|
+
* @example
|
|
114
|
+
* const position = await getListingMarketPosition({ siteId, listingId });
|
|
115
|
+
* const label = marketPositionLabel(position); // "8% abaixo da mediana do bairro"
|
|
116
|
+
*/
|
|
117
|
+
export async function getListingMarketPosition(
|
|
118
|
+
options: GetListingMarketPositionOptions
|
|
119
|
+
): Promise<ListingMarketPosition> {
|
|
120
|
+
const { listingId: rawListingId, baseUrl, fetch: fetchImpl, next } = options;
|
|
121
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
122
|
+
const listingId = listingLookupKey(rawListingId ?? "");
|
|
123
|
+
if (!listingId || listingId === "undefined" || listingId === "null") {
|
|
124
|
+
throw new TypeError("getListingMarketPosition: `listingId` is required");
|
|
125
|
+
}
|
|
126
|
+
const base = normalizeBaseUrl(baseUrl);
|
|
127
|
+
const url = `${base}/api/sites/${encodeURIComponent(siteId)}/listings/${encodeURIComponent(
|
|
128
|
+
listingId
|
|
129
|
+
)}/market-position`;
|
|
130
|
+
|
|
131
|
+
try {
|
|
132
|
+
return await callJson<ListingMarketPosition>(
|
|
133
|
+
url,
|
|
134
|
+
{ method: "GET", headers: { Accept: "application/json" }, next },
|
|
135
|
+
fetchImpl ?? fetch
|
|
136
|
+
);
|
|
137
|
+
} catch (error) {
|
|
138
|
+
if (!isRateLimited(error)) throw error;
|
|
139
|
+
return {
|
|
140
|
+
available: false,
|
|
141
|
+
reason: "rate_limited",
|
|
142
|
+
listingId,
|
|
143
|
+
city: null,
|
|
144
|
+
neighborhood: null,
|
|
145
|
+
months: 12,
|
|
146
|
+
listingPricePerSqmCents: null,
|
|
147
|
+
listingPricePerSqmFormatted: "—",
|
|
148
|
+
medianPricePerSqmCents: null,
|
|
149
|
+
medianPricePerSqmFormatted: "—",
|
|
150
|
+
percentVsMedian: null,
|
|
151
|
+
band: null,
|
|
152
|
+
sampleSize: null,
|
|
153
|
+
message: RATE_LIMITED_MESSAGE,
|
|
154
|
+
};
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Trimmed automated valuation (estimate, range, confidence) for
|
|
160
|
+
* visitor-entered characteristics. Never returns comparables.
|
|
161
|
+
*
|
|
162
|
+
* Limited per IP and per site; a limited call answers
|
|
163
|
+
* `reason: "rate_limited"`.
|
|
164
|
+
*
|
|
165
|
+
* @example
|
|
166
|
+
* const estimate = await requestPriceEstimate({
|
|
167
|
+
* siteId,
|
|
168
|
+
* input: { city: "sp", neighborhood: "Moema", areaSqm: 80, bedrooms: 2 },
|
|
169
|
+
* });
|
|
170
|
+
*/
|
|
171
|
+
export async function requestPriceEstimate(
|
|
172
|
+
options: RequestPriceEstimateOptions
|
|
173
|
+
): Promise<PriceEstimate> {
|
|
174
|
+
const { input, baseUrl, fetch: fetchImpl, next } = options;
|
|
175
|
+
const siteId = await coerceSiteId(options.siteId);
|
|
176
|
+
if (!input?.city?.trim() || typeof input.areaSqm !== "number") {
|
|
177
|
+
throw new TypeError(
|
|
178
|
+
"requestPriceEstimate: `input.city` and `input.areaSqm` are required"
|
|
179
|
+
);
|
|
180
|
+
}
|
|
181
|
+
const base = normalizeBaseUrl(baseUrl);
|
|
182
|
+
const url = `${base}/api/sites/${encodeURIComponent(siteId)}/market/estimate`;
|
|
183
|
+
|
|
184
|
+
try {
|
|
185
|
+
return await callJson<PriceEstimate>(
|
|
186
|
+
url,
|
|
187
|
+
{
|
|
188
|
+
method: "POST",
|
|
189
|
+
headers: {
|
|
190
|
+
Accept: "application/json",
|
|
191
|
+
"Content-Type": "application/json",
|
|
192
|
+
},
|
|
193
|
+
body: JSON.stringify(input),
|
|
194
|
+
next,
|
|
195
|
+
},
|
|
196
|
+
fetchImpl ?? fetch
|
|
197
|
+
);
|
|
198
|
+
} catch (error) {
|
|
199
|
+
if (!isRateLimited(error)) throw error;
|
|
200
|
+
return {
|
|
201
|
+
available: false,
|
|
202
|
+
reason: "rate_limited",
|
|
203
|
+
city: input.city,
|
|
204
|
+
neighborhood: input.neighborhood ?? null,
|
|
205
|
+
estimatedPriceCents: null,
|
|
206
|
+
estimatedPriceFormatted: "—",
|
|
207
|
+
rangeLowCents: null,
|
|
208
|
+
rangeHighCents: null,
|
|
209
|
+
rangeLowFormatted: "—",
|
|
210
|
+
rangeHighFormatted: "—",
|
|
211
|
+
confidenceLabel: null,
|
|
212
|
+
sampleSize: null,
|
|
213
|
+
message: RATE_LIMITED_MESSAGE,
|
|
214
|
+
};
|
|
215
|
+
}
|
|
216
|
+
}
|