@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/README.md +260 -28
- package/dist/index.d.mts +488 -150
- package/dist/index.d.ts +488 -150
- package/dist/index.js +882 -36
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +857 -36
- package/dist/index.mjs.map +1 -1
- package/dist/react.d.mts +46 -2
- package/dist/react.d.ts +46 -2
- package/dist/react.js +334 -14
- package/dist/react.js.map +1 -1
- package/dist/react.mjs +332 -14
- package/dist/react.mjs.map +1 -1
- package/dist/{search-engine-CtnLzmwW.d.mts → types-photo-search-CmGRj6my.d.mts} +229 -1
- package/dist/{search-engine-CtnLzmwW.d.ts → types-photo-search-CmGRj6my.d.ts} +229 -1
- package/package.json +2 -1
- package/src/client.ts +23 -0
- package/src/fetchers-market.ts +216 -0
- package/src/fetchers-photo-search.ts +101 -0
- package/src/fetchers-photos.ts +98 -0
- package/src/fetchers.ts +92 -29
- package/src/index.ts +92 -2
- package/src/internal/sdk-http.ts +122 -0
- package/src/leads.ts +34 -3
- package/src/listing-photos.ts +312 -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/types.ts +5 -0
- package/src/react/use-public-photo-search.ts +165 -0
- package/src/react/use-public-search.ts +23 -5
- package/src/resolve-site-id.ts +3 -0
- package/src/studio-contract.ts +178 -3
- package/src/types-market.ts +138 -0
- package/src/types-photo-search.ts +55 -0
- package/src/types-photos.ts +46 -0
- package/src/types.ts +18 -0
|
@@ -49,9 +49,20 @@ interface ListingMedia {
|
|
|
49
49
|
type: string;
|
|
50
50
|
category: string;
|
|
51
51
|
src: string;
|
|
52
|
+
/** Caption-based alt for photos with analysis; generic `"<title> - Foto N"` otherwise. */
|
|
52
53
|
alt?: string;
|
|
54
|
+
/** AI caption, falling back to the broker description. Photos only; absent when unanalyzed. */
|
|
53
55
|
caption?: string;
|
|
54
56
|
order?: number;
|
|
57
|
+
/**
|
|
58
|
+
* Room the photo shows, free text from the analysis (`sala`, `quarto`,
|
|
59
|
+
* `cozinha`, …). Group with `listingPhotoGroups`.
|
|
60
|
+
*/
|
|
61
|
+
roomType?: string;
|
|
62
|
+
/** `interior` | `facade` | `building_exterior` | `amenity` | `view` | `floorplan` | `other`. */
|
|
63
|
+
sceneType?: string;
|
|
64
|
+
/** Visual highlights named for this photo. Aggregate with `listingVisualHighlights`. */
|
|
65
|
+
features?: string[];
|
|
55
66
|
}
|
|
56
67
|
/**
|
|
57
68
|
* Minimum information needed to render a listing on a grid or card.
|
|
@@ -286,6 +297,13 @@ interface QueryListingsResult {
|
|
|
286
297
|
* This is the SDK's escape hatch when `queryListings` isn't expressive
|
|
287
298
|
* enough (faceted search, multi-field sort, custom grouping). It's an
|
|
288
299
|
* open dictionary on purpose; the only required field is `q`.
|
|
300
|
+
*
|
|
301
|
+
* The endpoint only forwards allowlisted query / filter / sort / pagination /
|
|
302
|
+
* facet / grouping / highlight params. Anything that would make Typesense
|
|
303
|
+
* call out (`vector_query`, `nl_query`, `conversation*`, `preset`,
|
|
304
|
+
* `remote_embedding_*`), curation overrides (`pinned_hits`, `hidden_hits`),
|
|
305
|
+
* `collection`, and embedding fields in `query_by` / `include_fields` are
|
|
306
|
+
* dropped server-side; `per_page` is capped at 250.
|
|
289
307
|
*/
|
|
290
308
|
interface SearchListingsParams {
|
|
291
309
|
q: string;
|
|
@@ -390,6 +408,166 @@ interface RequestNextOptions {
|
|
|
390
408
|
tags?: string[];
|
|
391
409
|
}
|
|
392
410
|
|
|
411
|
+
/** Custom fetch implementation. Defaults to the global `fetch`. */
|
|
412
|
+
type FetchLike = typeof fetch;
|
|
413
|
+
interface BaseOptions {
|
|
414
|
+
/** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
|
|
415
|
+
baseUrl?: string;
|
|
416
|
+
/** Override the fetch implementation (testing, edge runtimes, retries). */
|
|
417
|
+
fetch?: FetchLike;
|
|
418
|
+
/**
|
|
419
|
+
* Next.js App Router caching hints. Ignored on runtimes that don't
|
|
420
|
+
* understand them.
|
|
421
|
+
*/
|
|
422
|
+
next?: RequestNextOptions;
|
|
423
|
+
/**
|
|
424
|
+
* Site publishable key (`pk_live_…`) from Configurações → Sites → API
|
|
425
|
+
* pública. Not a secret. Omit it and the request stays anonymous.
|
|
426
|
+
*/
|
|
427
|
+
publishableKey?: string;
|
|
428
|
+
}
|
|
429
|
+
interface GetListingsOptions extends BaseOptions {
|
|
430
|
+
siteId: string;
|
|
431
|
+
filters?: ListingFilters;
|
|
432
|
+
}
|
|
433
|
+
interface GetListingOptions extends BaseOptions {
|
|
434
|
+
siteId: string;
|
|
435
|
+
listingId: string;
|
|
436
|
+
}
|
|
437
|
+
interface GetSiteOptions extends BaseOptions {
|
|
438
|
+
/** Look up by site ID, or… */
|
|
439
|
+
siteId?: string;
|
|
440
|
+
/** …by domain. Exactly one of `siteId` / `domain` must be provided. */
|
|
441
|
+
domain?: string;
|
|
442
|
+
}
|
|
443
|
+
interface SearchListingsOptions extends BaseOptions {
|
|
444
|
+
siteId: string;
|
|
445
|
+
params: SearchListingsParams;
|
|
446
|
+
}
|
|
447
|
+
interface GetSearchUiOptions extends BaseOptions {
|
|
448
|
+
siteId: string;
|
|
449
|
+
}
|
|
450
|
+
interface QueryListingsOptions extends BaseOptions {
|
|
451
|
+
siteId: string;
|
|
452
|
+
params?: QueryListingsParams;
|
|
453
|
+
}
|
|
454
|
+
interface GetSimilarListingsOptions extends BaseOptions {
|
|
455
|
+
siteId: string;
|
|
456
|
+
listingId: string;
|
|
457
|
+
/** Max similar cards to return (API default 6, cap 12). */
|
|
458
|
+
limit?: number;
|
|
459
|
+
}
|
|
460
|
+
interface GetCmsCollectionsOptions extends BaseOptions {
|
|
461
|
+
siteId: string;
|
|
462
|
+
}
|
|
463
|
+
interface GetCmsCollectionOptions extends BaseOptions {
|
|
464
|
+
siteId: string;
|
|
465
|
+
slug: string;
|
|
466
|
+
}
|
|
467
|
+
interface GetCmsEntriesOptions extends BaseOptions {
|
|
468
|
+
siteId: string;
|
|
469
|
+
collection: string;
|
|
470
|
+
limit?: number;
|
|
471
|
+
offset?: number;
|
|
472
|
+
}
|
|
473
|
+
interface GetCmsEntryOptions extends BaseOptions {
|
|
474
|
+
siteId: string;
|
|
475
|
+
collection: string;
|
|
476
|
+
slug: string;
|
|
477
|
+
}
|
|
478
|
+
/** Error thrown when a fetcher hits a non-2xx response. */
|
|
479
|
+
declare class GaragemSdkError extends Error {
|
|
480
|
+
readonly status: number;
|
|
481
|
+
readonly url: string;
|
|
482
|
+
/** Machine reason from the JSON body (`invalid_publishable_key`, `rate_limited`, …). */
|
|
483
|
+
readonly reason: string | null;
|
|
484
|
+
/**
|
|
485
|
+
* Seconds to wait before retrying. Set on HTTP 429 from `Retry-After`
|
|
486
|
+
* or the body's `retryAfterSeconds`. `null` when the response has neither.
|
|
487
|
+
*/
|
|
488
|
+
readonly retryAfter: number | null;
|
|
489
|
+
constructor(message: string, info: {
|
|
490
|
+
status: number;
|
|
491
|
+
url: string;
|
|
492
|
+
reason?: string | null;
|
|
493
|
+
retryAfter?: number | null;
|
|
494
|
+
});
|
|
495
|
+
}
|
|
496
|
+
/**
|
|
497
|
+
* Fetch a paginated list of listings for a given site.
|
|
498
|
+
*
|
|
499
|
+
* @example
|
|
500
|
+
* const { listings } = await getListings({
|
|
501
|
+
* siteId: "abc",
|
|
502
|
+
* filters: { city: "São Paulo", limit: 24 },
|
|
503
|
+
* next: { revalidate: 300, tags: [`site:abc:listings`] },
|
|
504
|
+
* });
|
|
505
|
+
*/
|
|
506
|
+
declare function getListings(options: GetListingsOptions): Promise<ListingsResult>;
|
|
507
|
+
/**
|
|
508
|
+
* Fetch a single listing's full detail (amenities, gallery, building).
|
|
509
|
+
* `listingId` accepts a code, UUID, or `id-{code}` URL segment.
|
|
510
|
+
*/
|
|
511
|
+
declare function getListing(options: GetListingOptions): Promise<ListingDetail>;
|
|
512
|
+
/**
|
|
513
|
+
* Resolve a site's public profile by ID or by domain. Returns `null`
|
|
514
|
+
* when the site does not exist or the host is unrecognized.
|
|
515
|
+
*
|
|
516
|
+
* @example
|
|
517
|
+
* const site = await getSite({ domain: "imobiliariax.com.br" });
|
|
518
|
+
* if (!site) return notFound();
|
|
519
|
+
*/
|
|
520
|
+
declare function getSite(options: GetSiteOptions): Promise<Site | null>;
|
|
521
|
+
/**
|
|
522
|
+
* Advanced search escape hatch.
|
|
523
|
+
*
|
|
524
|
+
* Calls `POST /api/sites/{siteId}/search` directly and returns the raw
|
|
525
|
+
* Typesense response (`{ found, page, hits: [{ document, ... }], ... }`).
|
|
526
|
+
* Use when `queryListings` isn't expressive enough — faceted search,
|
|
527
|
+
* multi-field sort, custom grouping, etc.
|
|
528
|
+
*
|
|
529
|
+
* @example
|
|
530
|
+
* const result = await searchListings({
|
|
531
|
+
* siteId: "abc",
|
|
532
|
+
* params: {
|
|
533
|
+
* q: "frente mar",
|
|
534
|
+
* query_by: "title,description,neighborhood",
|
|
535
|
+
* filter_by: "businessType:=sale && bedrooms:>=3",
|
|
536
|
+
* sort_by: "price:asc",
|
|
537
|
+
* per_page: 24,
|
|
538
|
+
* page: 1,
|
|
539
|
+
* facet_by: "neighborhood,propertyType",
|
|
540
|
+
* },
|
|
541
|
+
* });
|
|
542
|
+
* for (const hit of result.hits) {
|
|
543
|
+
* console.log(hit.document, hit.highlight);
|
|
544
|
+
* }
|
|
545
|
+
*/
|
|
546
|
+
declare function searchListings<TDocument = Record<string, unknown>>(options: SearchListingsOptions): Promise<SearchListingsResult<TDocument>>;
|
|
547
|
+
/**
|
|
548
|
+
* Tenant search schema: filters, slugs, sort tokens, defaultLimit 12.
|
|
549
|
+
* Use this to render the search UI — do not hardcode property types.
|
|
550
|
+
*/
|
|
551
|
+
declare function getSearchUi(options: GetSearchUiOptions): Promise<SearchUi>;
|
|
552
|
+
/**
|
|
553
|
+
* Friendly catalog search (editor combinators). Prefer this over
|
|
554
|
+
* `searchListings` — that helper is a raw Typesense escape hatch.
|
|
555
|
+
*/
|
|
556
|
+
declare function queryListings(options: QueryListingsOptions): Promise<QueryListingsResult>;
|
|
557
|
+
/**
|
|
558
|
+
* Fetch similar listings for a detail page carousel.
|
|
559
|
+
* Returns an empty list when the reference listing is missing.
|
|
560
|
+
*/
|
|
561
|
+
declare function getSimilarListings(options: GetSimilarListingsOptions): Promise<SimilarListingsResult>;
|
|
562
|
+
/** List CMS collections for a site. */
|
|
563
|
+
declare function getCmsCollections(options: GetCmsCollectionsOptions): Promise<CmsCollection[]>;
|
|
564
|
+
/** Fetch one CMS collection schema by slug. */
|
|
565
|
+
declare function getCmsCollection(options: GetCmsCollectionOptions): Promise<CmsCollection>;
|
|
566
|
+
/** List published CMS entries for a collection. */
|
|
567
|
+
declare function getCmsEntries(options: GetCmsEntriesOptions): Promise<CmsEntriesResult>;
|
|
568
|
+
/** Fetch one published CMS entry by slug. */
|
|
569
|
+
declare function getCmsEntry(options: GetCmsEntryOptions): Promise<CmsEntry>;
|
|
570
|
+
|
|
393
571
|
/** Query keys that must never encode filters (Editor/Studio path contract). */
|
|
394
572
|
declare const FORBIDDEN_SEARCH_QUERY_KEYS: readonly ["tipo", "quartos", "tipo-imovel", "banheiros", "vagas"];
|
|
395
573
|
/** Default option: omit `ordenar` (API has no relevance token). */
|
|
@@ -471,4 +649,54 @@ type SearchChromeModel = {
|
|
|
471
649
|
};
|
|
472
650
|
declare function searchChromeModel(schema: SearchUi | null, pathFilters: SearchPathFilters, locationNames?: LocationNameTables | null): SearchChromeModel;
|
|
473
651
|
|
|
474
|
-
|
|
652
|
+
/**
|
|
653
|
+
* "Busca pelo que as fotos mostram": search a site's catalog by what the
|
|
654
|
+
* public photos show (`GET /api/sites/{siteId}/search/photos`).
|
|
655
|
+
*/
|
|
656
|
+
interface PhotoSearchParams {
|
|
657
|
+
/** Free text describing the photo ("varanda gourmet com churrasqueira"). */
|
|
658
|
+
q: string;
|
|
659
|
+
/** Listings per page (API default 12, cap 24). */
|
|
660
|
+
limit?: number;
|
|
661
|
+
/** 1-based page inside the API's candidate window. */
|
|
662
|
+
page?: number;
|
|
663
|
+
}
|
|
664
|
+
/** The photo that matched the words, chosen the same way as the CRM cover switch. */
|
|
665
|
+
interface MatchedListingPhoto {
|
|
666
|
+
/** Media id; stable across listings that share the same photo. */
|
|
667
|
+
id: string;
|
|
668
|
+
src: string;
|
|
669
|
+
alt: string;
|
|
670
|
+
caption: string | null;
|
|
671
|
+
/**
|
|
672
|
+
* Vector distance for a visual match (lower is closer). `null` when the
|
|
673
|
+
* photo matched through its caption / room type instead (an exact text
|
|
674
|
+
* match, accepted as-is by {@link applyMatchedPhotoCover}).
|
|
675
|
+
*/
|
|
676
|
+
distance: number | null;
|
|
677
|
+
}
|
|
678
|
+
interface PhotoSearchItem {
|
|
679
|
+
/** Same card shape as `getListings` / `queryListings`. */
|
|
680
|
+
listing: Listing;
|
|
681
|
+
matchedPhoto: MatchedListingPhoto;
|
|
682
|
+
/** Lane score; higher is closer. Items arrive nearest-first. */
|
|
683
|
+
score: number;
|
|
684
|
+
}
|
|
685
|
+
interface PhotoSearchResult {
|
|
686
|
+
/**
|
|
687
|
+
* `false` when the tenant has not enabled photo search: `items` is empty
|
|
688
|
+
* and the site should hide the feature rather than show "no results".
|
|
689
|
+
*/
|
|
690
|
+
available: boolean;
|
|
691
|
+
items: PhotoSearchItem[];
|
|
692
|
+
/** Matching listings across every page (bounded by the API candidate window). */
|
|
693
|
+
total: number;
|
|
694
|
+
page: number;
|
|
695
|
+
limit: number;
|
|
696
|
+
}
|
|
697
|
+
/** A listing card whose cover was swapped for the photo that matched the search. */
|
|
698
|
+
type ListingWithMatchedPhoto = Listing & {
|
|
699
|
+
matchedPhoto: MatchedListingPhoto | null;
|
|
700
|
+
};
|
|
701
|
+
|
|
702
|
+
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 };
|
|
@@ -49,9 +49,20 @@ interface ListingMedia {
|
|
|
49
49
|
type: string;
|
|
50
50
|
category: string;
|
|
51
51
|
src: string;
|
|
52
|
+
/** Caption-based alt for photos with analysis; generic `"<title> - Foto N"` otherwise. */
|
|
52
53
|
alt?: string;
|
|
54
|
+
/** AI caption, falling back to the broker description. Photos only; absent when unanalyzed. */
|
|
53
55
|
caption?: string;
|
|
54
56
|
order?: number;
|
|
57
|
+
/**
|
|
58
|
+
* Room the photo shows, free text from the analysis (`sala`, `quarto`,
|
|
59
|
+
* `cozinha`, …). Group with `listingPhotoGroups`.
|
|
60
|
+
*/
|
|
61
|
+
roomType?: string;
|
|
62
|
+
/** `interior` | `facade` | `building_exterior` | `amenity` | `view` | `floorplan` | `other`. */
|
|
63
|
+
sceneType?: string;
|
|
64
|
+
/** Visual highlights named for this photo. Aggregate with `listingVisualHighlights`. */
|
|
65
|
+
features?: string[];
|
|
55
66
|
}
|
|
56
67
|
/**
|
|
57
68
|
* Minimum information needed to render a listing on a grid or card.
|
|
@@ -286,6 +297,13 @@ interface QueryListingsResult {
|
|
|
286
297
|
* This is the SDK's escape hatch when `queryListings` isn't expressive
|
|
287
298
|
* enough (faceted search, multi-field sort, custom grouping). It's an
|
|
288
299
|
* open dictionary on purpose; the only required field is `q`.
|
|
300
|
+
*
|
|
301
|
+
* The endpoint only forwards allowlisted query / filter / sort / pagination /
|
|
302
|
+
* facet / grouping / highlight params. Anything that would make Typesense
|
|
303
|
+
* call out (`vector_query`, `nl_query`, `conversation*`, `preset`,
|
|
304
|
+
* `remote_embedding_*`), curation overrides (`pinned_hits`, `hidden_hits`),
|
|
305
|
+
* `collection`, and embedding fields in `query_by` / `include_fields` are
|
|
306
|
+
* dropped server-side; `per_page` is capped at 250.
|
|
289
307
|
*/
|
|
290
308
|
interface SearchListingsParams {
|
|
291
309
|
q: string;
|
|
@@ -390,6 +408,166 @@ interface RequestNextOptions {
|
|
|
390
408
|
tags?: string[];
|
|
391
409
|
}
|
|
392
410
|
|
|
411
|
+
/** Custom fetch implementation. Defaults to the global `fetch`. */
|
|
412
|
+
type FetchLike = typeof fetch;
|
|
413
|
+
interface BaseOptions {
|
|
414
|
+
/** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
|
|
415
|
+
baseUrl?: string;
|
|
416
|
+
/** Override the fetch implementation (testing, edge runtimes, retries). */
|
|
417
|
+
fetch?: FetchLike;
|
|
418
|
+
/**
|
|
419
|
+
* Next.js App Router caching hints. Ignored on runtimes that don't
|
|
420
|
+
* understand them.
|
|
421
|
+
*/
|
|
422
|
+
next?: RequestNextOptions;
|
|
423
|
+
/**
|
|
424
|
+
* Site publishable key (`pk_live_…`) from Configurações → Sites → API
|
|
425
|
+
* pública. Not a secret. Omit it and the request stays anonymous.
|
|
426
|
+
*/
|
|
427
|
+
publishableKey?: string;
|
|
428
|
+
}
|
|
429
|
+
interface GetListingsOptions extends BaseOptions {
|
|
430
|
+
siteId: string;
|
|
431
|
+
filters?: ListingFilters;
|
|
432
|
+
}
|
|
433
|
+
interface GetListingOptions extends BaseOptions {
|
|
434
|
+
siteId: string;
|
|
435
|
+
listingId: string;
|
|
436
|
+
}
|
|
437
|
+
interface GetSiteOptions extends BaseOptions {
|
|
438
|
+
/** Look up by site ID, or… */
|
|
439
|
+
siteId?: string;
|
|
440
|
+
/** …by domain. Exactly one of `siteId` / `domain` must be provided. */
|
|
441
|
+
domain?: string;
|
|
442
|
+
}
|
|
443
|
+
interface SearchListingsOptions extends BaseOptions {
|
|
444
|
+
siteId: string;
|
|
445
|
+
params: SearchListingsParams;
|
|
446
|
+
}
|
|
447
|
+
interface GetSearchUiOptions extends BaseOptions {
|
|
448
|
+
siteId: string;
|
|
449
|
+
}
|
|
450
|
+
interface QueryListingsOptions extends BaseOptions {
|
|
451
|
+
siteId: string;
|
|
452
|
+
params?: QueryListingsParams;
|
|
453
|
+
}
|
|
454
|
+
interface GetSimilarListingsOptions extends BaseOptions {
|
|
455
|
+
siteId: string;
|
|
456
|
+
listingId: string;
|
|
457
|
+
/** Max similar cards to return (API default 6, cap 12). */
|
|
458
|
+
limit?: number;
|
|
459
|
+
}
|
|
460
|
+
interface GetCmsCollectionsOptions extends BaseOptions {
|
|
461
|
+
siteId: string;
|
|
462
|
+
}
|
|
463
|
+
interface GetCmsCollectionOptions extends BaseOptions {
|
|
464
|
+
siteId: string;
|
|
465
|
+
slug: string;
|
|
466
|
+
}
|
|
467
|
+
interface GetCmsEntriesOptions extends BaseOptions {
|
|
468
|
+
siteId: string;
|
|
469
|
+
collection: string;
|
|
470
|
+
limit?: number;
|
|
471
|
+
offset?: number;
|
|
472
|
+
}
|
|
473
|
+
interface GetCmsEntryOptions extends BaseOptions {
|
|
474
|
+
siteId: string;
|
|
475
|
+
collection: string;
|
|
476
|
+
slug: string;
|
|
477
|
+
}
|
|
478
|
+
/** Error thrown when a fetcher hits a non-2xx response. */
|
|
479
|
+
declare class GaragemSdkError extends Error {
|
|
480
|
+
readonly status: number;
|
|
481
|
+
readonly url: string;
|
|
482
|
+
/** Machine reason from the JSON body (`invalid_publishable_key`, `rate_limited`, …). */
|
|
483
|
+
readonly reason: string | null;
|
|
484
|
+
/**
|
|
485
|
+
* Seconds to wait before retrying. Set on HTTP 429 from `Retry-After`
|
|
486
|
+
* or the body's `retryAfterSeconds`. `null` when the response has neither.
|
|
487
|
+
*/
|
|
488
|
+
readonly retryAfter: number | null;
|
|
489
|
+
constructor(message: string, info: {
|
|
490
|
+
status: number;
|
|
491
|
+
url: string;
|
|
492
|
+
reason?: string | null;
|
|
493
|
+
retryAfter?: number | null;
|
|
494
|
+
});
|
|
495
|
+
}
|
|
496
|
+
/**
|
|
497
|
+
* Fetch a paginated list of listings for a given site.
|
|
498
|
+
*
|
|
499
|
+
* @example
|
|
500
|
+
* const { listings } = await getListings({
|
|
501
|
+
* siteId: "abc",
|
|
502
|
+
* filters: { city: "São Paulo", limit: 24 },
|
|
503
|
+
* next: { revalidate: 300, tags: [`site:abc:listings`] },
|
|
504
|
+
* });
|
|
505
|
+
*/
|
|
506
|
+
declare function getListings(options: GetListingsOptions): Promise<ListingsResult>;
|
|
507
|
+
/**
|
|
508
|
+
* Fetch a single listing's full detail (amenities, gallery, building).
|
|
509
|
+
* `listingId` accepts a code, UUID, or `id-{code}` URL segment.
|
|
510
|
+
*/
|
|
511
|
+
declare function getListing(options: GetListingOptions): Promise<ListingDetail>;
|
|
512
|
+
/**
|
|
513
|
+
* Resolve a site's public profile by ID or by domain. Returns `null`
|
|
514
|
+
* when the site does not exist or the host is unrecognized.
|
|
515
|
+
*
|
|
516
|
+
* @example
|
|
517
|
+
* const site = await getSite({ domain: "imobiliariax.com.br" });
|
|
518
|
+
* if (!site) return notFound();
|
|
519
|
+
*/
|
|
520
|
+
declare function getSite(options: GetSiteOptions): Promise<Site | null>;
|
|
521
|
+
/**
|
|
522
|
+
* Advanced search escape hatch.
|
|
523
|
+
*
|
|
524
|
+
* Calls `POST /api/sites/{siteId}/search` directly and returns the raw
|
|
525
|
+
* Typesense response (`{ found, page, hits: [{ document, ... }], ... }`).
|
|
526
|
+
* Use when `queryListings` isn't expressive enough — faceted search,
|
|
527
|
+
* multi-field sort, custom grouping, etc.
|
|
528
|
+
*
|
|
529
|
+
* @example
|
|
530
|
+
* const result = await searchListings({
|
|
531
|
+
* siteId: "abc",
|
|
532
|
+
* params: {
|
|
533
|
+
* q: "frente mar",
|
|
534
|
+
* query_by: "title,description,neighborhood",
|
|
535
|
+
* filter_by: "businessType:=sale && bedrooms:>=3",
|
|
536
|
+
* sort_by: "price:asc",
|
|
537
|
+
* per_page: 24,
|
|
538
|
+
* page: 1,
|
|
539
|
+
* facet_by: "neighborhood,propertyType",
|
|
540
|
+
* },
|
|
541
|
+
* });
|
|
542
|
+
* for (const hit of result.hits) {
|
|
543
|
+
* console.log(hit.document, hit.highlight);
|
|
544
|
+
* }
|
|
545
|
+
*/
|
|
546
|
+
declare function searchListings<TDocument = Record<string, unknown>>(options: SearchListingsOptions): Promise<SearchListingsResult<TDocument>>;
|
|
547
|
+
/**
|
|
548
|
+
* Tenant search schema: filters, slugs, sort tokens, defaultLimit 12.
|
|
549
|
+
* Use this to render the search UI — do not hardcode property types.
|
|
550
|
+
*/
|
|
551
|
+
declare function getSearchUi(options: GetSearchUiOptions): Promise<SearchUi>;
|
|
552
|
+
/**
|
|
553
|
+
* Friendly catalog search (editor combinators). Prefer this over
|
|
554
|
+
* `searchListings` — that helper is a raw Typesense escape hatch.
|
|
555
|
+
*/
|
|
556
|
+
declare function queryListings(options: QueryListingsOptions): Promise<QueryListingsResult>;
|
|
557
|
+
/**
|
|
558
|
+
* Fetch similar listings for a detail page carousel.
|
|
559
|
+
* Returns an empty list when the reference listing is missing.
|
|
560
|
+
*/
|
|
561
|
+
declare function getSimilarListings(options: GetSimilarListingsOptions): Promise<SimilarListingsResult>;
|
|
562
|
+
/** List CMS collections for a site. */
|
|
563
|
+
declare function getCmsCollections(options: GetCmsCollectionsOptions): Promise<CmsCollection[]>;
|
|
564
|
+
/** Fetch one CMS collection schema by slug. */
|
|
565
|
+
declare function getCmsCollection(options: GetCmsCollectionOptions): Promise<CmsCollection>;
|
|
566
|
+
/** List published CMS entries for a collection. */
|
|
567
|
+
declare function getCmsEntries(options: GetCmsEntriesOptions): Promise<CmsEntriesResult>;
|
|
568
|
+
/** Fetch one published CMS entry by slug. */
|
|
569
|
+
declare function getCmsEntry(options: GetCmsEntryOptions): Promise<CmsEntry>;
|
|
570
|
+
|
|
393
571
|
/** Query keys that must never encode filters (Editor/Studio path contract). */
|
|
394
572
|
declare const FORBIDDEN_SEARCH_QUERY_KEYS: readonly ["tipo", "quartos", "tipo-imovel", "banheiros", "vagas"];
|
|
395
573
|
/** Default option: omit `ordenar` (API has no relevance token). */
|
|
@@ -471,4 +649,54 @@ type SearchChromeModel = {
|
|
|
471
649
|
};
|
|
472
650
|
declare function searchChromeModel(schema: SearchUi | null, pathFilters: SearchPathFilters, locationNames?: LocationNameTables | null): SearchChromeModel;
|
|
473
651
|
|
|
474
|
-
|
|
652
|
+
/**
|
|
653
|
+
* "Busca pelo que as fotos mostram": search a site's catalog by what the
|
|
654
|
+
* public photos show (`GET /api/sites/{siteId}/search/photos`).
|
|
655
|
+
*/
|
|
656
|
+
interface PhotoSearchParams {
|
|
657
|
+
/** Free text describing the photo ("varanda gourmet com churrasqueira"). */
|
|
658
|
+
q: string;
|
|
659
|
+
/** Listings per page (API default 12, cap 24). */
|
|
660
|
+
limit?: number;
|
|
661
|
+
/** 1-based page inside the API's candidate window. */
|
|
662
|
+
page?: number;
|
|
663
|
+
}
|
|
664
|
+
/** The photo that matched the words, chosen the same way as the CRM cover switch. */
|
|
665
|
+
interface MatchedListingPhoto {
|
|
666
|
+
/** Media id; stable across listings that share the same photo. */
|
|
667
|
+
id: string;
|
|
668
|
+
src: string;
|
|
669
|
+
alt: string;
|
|
670
|
+
caption: string | null;
|
|
671
|
+
/**
|
|
672
|
+
* Vector distance for a visual match (lower is closer). `null` when the
|
|
673
|
+
* photo matched through its caption / room type instead (an exact text
|
|
674
|
+
* match, accepted as-is by {@link applyMatchedPhotoCover}).
|
|
675
|
+
*/
|
|
676
|
+
distance: number | null;
|
|
677
|
+
}
|
|
678
|
+
interface PhotoSearchItem {
|
|
679
|
+
/** Same card shape as `getListings` / `queryListings`. */
|
|
680
|
+
listing: Listing;
|
|
681
|
+
matchedPhoto: MatchedListingPhoto;
|
|
682
|
+
/** Lane score; higher is closer. Items arrive nearest-first. */
|
|
683
|
+
score: number;
|
|
684
|
+
}
|
|
685
|
+
interface PhotoSearchResult {
|
|
686
|
+
/**
|
|
687
|
+
* `false` when the tenant has not enabled photo search: `items` is empty
|
|
688
|
+
* and the site should hide the feature rather than show "no results".
|
|
689
|
+
*/
|
|
690
|
+
available: boolean;
|
|
691
|
+
items: PhotoSearchItem[];
|
|
692
|
+
/** Matching listings across every page (bounded by the API candidate window). */
|
|
693
|
+
total: number;
|
|
694
|
+
page: number;
|
|
695
|
+
limit: number;
|
|
696
|
+
}
|
|
697
|
+
/** A listing card whose cover was swapped for the photo that matched the search. */
|
|
698
|
+
type ListingWithMatchedPhoto = Listing & {
|
|
699
|
+
matchedPhoto: MatchedListingPhoto | null;
|
|
700
|
+
};
|
|
701
|
+
|
|
702
|
+
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.8.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",
|
package/src/client.ts
CHANGED
|
@@ -55,6 +55,12 @@ export interface CreateGaragemClientOptions {
|
|
|
55
55
|
baseUrl?: string;
|
|
56
56
|
/** Pre-bind a site so each call doesn't repeat it. */
|
|
57
57
|
siteId?: string;
|
|
58
|
+
/**
|
|
59
|
+
* Publishable key (`pk_live_…`) from the site's API pública settings.
|
|
60
|
+
* Sent as `X-Garagem-Publishable-Key` on every request. Not a secret.
|
|
61
|
+
* Omit it to keep the anonymous per-IP budget.
|
|
62
|
+
*/
|
|
63
|
+
publishableKey?: string;
|
|
58
64
|
/** Custom fetch implementation. */
|
|
59
65
|
fetch?: FetchLike;
|
|
60
66
|
/** Default Next.js caching hints applied to every request. */
|
|
@@ -187,14 +193,22 @@ export function createGaragemClient(
|
|
|
187
193
|
baseUrl?: string;
|
|
188
194
|
fetch?: FetchLike;
|
|
189
195
|
next?: RequestNextOptions;
|
|
196
|
+
publishableKey?: string;
|
|
190
197
|
} => {
|
|
191
198
|
const out: T & {
|
|
192
199
|
baseUrl?: string;
|
|
193
200
|
fetch?: FetchLike;
|
|
194
201
|
next?: RequestNextOptions;
|
|
202
|
+
publishableKey?: string;
|
|
195
203
|
} = { ...opts };
|
|
196
204
|
if (options.baseUrl !== undefined) out.baseUrl = options.baseUrl;
|
|
197
205
|
if (options.fetch !== undefined) out.fetch = options.fetch;
|
|
206
|
+
if (
|
|
207
|
+
options.publishableKey !== undefined &&
|
|
208
|
+
out.publishableKey === undefined
|
|
209
|
+
) {
|
|
210
|
+
out.publishableKey = options.publishableKey;
|
|
211
|
+
}
|
|
198
212
|
return out;
|
|
199
213
|
};
|
|
200
214
|
|
|
@@ -227,6 +241,9 @@ export function createGaragemClient(
|
|
|
227
241
|
if (domain !== undefined) opts.domain = domain;
|
|
228
242
|
if (options.baseUrl !== undefined) opts.baseUrl = options.baseUrl;
|
|
229
243
|
if (options.fetch !== undefined) opts.fetch = options.fetch;
|
|
244
|
+
if (options.publishableKey !== undefined) {
|
|
245
|
+
opts.publishableKey = options.publishableKey;
|
|
246
|
+
}
|
|
230
247
|
const merged = mergeNext(next);
|
|
231
248
|
if (merged !== undefined) opts.next = merged;
|
|
232
249
|
return getSite(opts);
|
|
@@ -339,3 +356,9 @@ export function createGaragemClient(
|
|
|
339
356
|
},
|
|
340
357
|
};
|
|
341
358
|
}
|
|
359
|
+
|
|
360
|
+
/**
|
|
361
|
+
* Alias of {@link createGaragemClient}. `createClient({ publishableKey })`
|
|
362
|
+
* binds the key the same way.
|
|
363
|
+
*/
|
|
364
|
+
export const createClient = createGaragemClient;
|