SDK Reference

Complete API reference for @garagem-ai/site-sdk.

Installation

pnpm add @garagem-ai/site-sdk

Two usage styles — bare functions or a bound client:

// Bare functions
import { getListings, getListing, getSite, searchListings } from "@garagem-ai/site-sdk";

// Bound client (defaults siteId + baseUrl)
import { createGaragemClient } from "@garagem-ai/site-sdk";
const garagem = createGaragemClient({ siteId: "abc" });
const { listings } = await garagem.getListings();

Fetcher Functions

getListings

Fetch a paginated list of listings for a site. Supports filtering by business type, property type, location, and price range.

function getListings(options: GetListingsOptions): Promise<ListingsResult>

Parameters

Name	Type	Description
siteId	string	Garagem site ID
filters?	ListingFilters	limit, offset, businessType, propertyType, city, neighborhood, minPrice, maxPrice
baseUrl?	string	API base. Defaults to https://app.garagem.ai
next?	{ revalidate?, tags? }	Next.js App Router caching hints

Example

const { listings, total } = await getListings({
  siteId: "abc-123",
  filters: {
    city: "São Paulo",
    businessType: "sale",
    minPrice: 500_000,
    limit: 24,
    offset: 0,
  },
  next: { revalidate: 300, tags: ["listings"] },
});

getListing

Fetch a single listing's full detail including amenities, media gallery, building info, and extended property data.

function getListing(options: GetListingOptions): Promise<ListingDetail>

Parameters

Name	Type	Description
siteId	string	Garagem site ID
listingId	string	The listing's unique ID
baseUrl?	string	API base. Defaults to https://app.garagem.ai
next?	{ revalidate?, tags? }	Next.js App Router caching hints

Example

const listing = await getListing({
  siteId: "abc-123",
  listingId: "listing-456",
  next: { revalidate: 60 },
});
// listing.amenities, listing.media, listing.building, etc.

getSite

Resolve a site by ID or domain. Returns null if not found. Useful for multi-tenant setups where the site ID isn't known ahead of time.

function getSite(options: GetSiteOptions): Promise<Site | null>

Parameters

Name	Type	Description
siteId?	string	Look up by site ID
domain?	string	Or look up by domain (exactly one must be provided)
baseUrl?	string	API base. Defaults to https://app.garagem.ai

Example

const site = await getSite({ domain: "imobiliariax.com.br" });
if (!site) return notFound();
// site.id, site.name, site.domain, site.tenantId

searchListings

Advanced Typesense search escape hatch. Use when getListings isn't expressive enough — faceted search, multi-field sort, custom grouping, highlighting.

function searchListings<TDocument>(options: SearchListingsOptions): Promise<SearchListingsResult<TDocument>>

Parameters

Name	Type	Description
siteId	string	Garagem site ID
params	SearchListingsParams	Raw Typesense params: q, query_by, filter_by, sort_by, per_page, page, facet_by, group_by, etc.
baseUrl?	string	API base. Defaults to https://app.garagem.ai

Example

const result = await searchListings({
  siteId: "abc-123",
  params: {
    q: "frente mar",
    query_by: "title,description,neighborhood",
    filter_by: "businessType:=sale && bedrooms:>=3",
    sort_by: "price:asc",
    per_page: 24,
    facet_by: "neighborhood,propertyType",
  },
});
// result.found, result.hits[].document, result.hits[].highlight

createGaragemClient

Create a bound client that pre-fills siteId and baseUrl on every call. Convenient when you call multiple SDK functions with the same config.

function createGaragemClient(options: CreateGaragemClientOptions): GaragemClient

Parameters

Name	Type	Description
siteId	string	Garagem site ID
baseUrl?	string	API base. Defaults to https://app.garagem.ai
fetch?	FetchLike	Custom fetch implementation

Example

import { createGaragemClient } from "@garagem-ai/site-sdk";

const garagem = createGaragemClient({
  siteId: process.env.GARAGEM_SITE_ID!,
});

const { listings } = await garagem.getListings({ filters: { limit: 12 } });
const detail = await garagem.getListing({ listingId: "xyz" });

Types

Listing

Summary shape returned by getListings. Contains enough info to render a card.

interface Listing {
  id: string
  title: string
  description: string
  businessType: "sale" | "rental" | string
  price: number | null
  priceVisibility: "public" | "private"
  status: string
  featured: boolean
  property: ListingPropertySummary
  location: ListingLocation
  coverImage?: { src: string; alt: string } | null
  createdAt: string
  updatedAt: string
}

ListingDetail

Full listing data returned by getListing. Extends Listing with gallery, amenities, and building info.

interface ListingDetail {
  ...Listing
  amenities: string[]
  tags: string[]
  property: ListingPropertySummary & { id, builtArea?, landArea?, floor?, totalFloors?, yearBuilt?, furnished?, petFriendly? }
  building?: { name, amenities, elevators?, unitsPerFloor?, totalUnits? } | null
  media: ListingMedia[]
}

ListingPropertySummary

Property-level fields on a listing.

interface ListingPropertySummary {
  type: string
  bedrooms: number
  bathrooms: number
  suites: number
  parkingSpaces: number
  totalArea: number
  usableArea: number
}

ListingLocation

Address breakdown.

interface ListingLocation {
  street: string
  number: string
  complement?: string
  neighborhood: string
  city: string
  state: string
  postalCode: string
  country?: string
  coordinates?: { lat: number; lng: number } | null
}

ListingMedia

Single media item attached to a listing.

interface ListingMedia {
  id: string
  type: string
  category: string
  src: string
  alt?: string
  caption?: string
  order?: number
}

Site

Public summary of a Garagem-managed site.

interface Site {
  id: string
  name: string
  domain: string | null
  tenantId: string
}

GaragemSdkError

Thrown when a fetcher hits a non-2xx response.

interface GaragemSdkError {
  message: string
  status: number (HTTP status code)
  url: string (the request URL)
}