@garagem-ai/site-sdk 0.1.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/src/index.ts ADDED
@@ -0,0 +1,55 @@
1
+ /**
2
+ * @garagem-ai/site-sdk — typed, runtime-agnostic SDK for building
3
+ * custom real estate sites against the Garagem platform.
4
+ *
5
+ * Two usage styles:
6
+ *
7
+ * 1. Bare functions (simple):
8
+ *
9
+ * import { getListings } from "@garagem-ai/site-sdk";
10
+ * const { listings } = await getListings({ siteId: "abc" });
11
+ *
12
+ * 2. Client object (binds defaults):
13
+ *
14
+ * import { createGaragemClient } from "@garagem-ai/site-sdk";
15
+ * const garagem = createGaragemClient({ siteId: "abc" });
16
+ * const { listings } = await garagem.getListings();
17
+ *
18
+ * Works in Node, Edge runtimes, Cloudflare Workers, Bun, Deno and the
19
+ * browser — anywhere `fetch` is available.
20
+ */
21
+
22
+ export type {
23
+ Listing,
24
+ ListingBusinessType,
25
+ ListingDetail,
26
+ ListingFilters,
27
+ ListingLocation,
28
+ ListingMedia,
29
+ ListingPriceVisibility,
30
+ ListingPropertySummary,
31
+ ListingsResult,
32
+ RequestNextOptions,
33
+ SearchListingsParams,
34
+ SearchListingsResult,
35
+ Site,
36
+ } from "./types";
37
+
38
+ export {
39
+ getListing,
40
+ getListings,
41
+ getSite,
42
+ searchListings,
43
+ GaragemSdkError,
44
+ type FetchLike,
45
+ type GetListingOptions,
46
+ type GetListingsOptions,
47
+ type GetSiteOptions,
48
+ type SearchListingsOptions,
49
+ } from "./fetchers";
50
+
51
+ export {
52
+ createGaragemClient,
53
+ type CreateGaragemClientOptions,
54
+ type GaragemClient,
55
+ } from "./client";
@@ -0,0 +1,32 @@
1
+ import type { ListingFilters } from "../types";
2
+
3
+ /** Default base URL — the public Garagem API. Override via `baseUrl`. */
4
+ export const DEFAULT_BASE_URL = "https://app.garagem.ai";
5
+
6
+ export function normalizeBaseUrl(baseUrl: string | undefined): string {
7
+ const url = baseUrl ?? DEFAULT_BASE_URL;
8
+ return url.endsWith("/") ? url.slice(0, -1) : url;
9
+ }
10
+
11
+ /**
12
+ * Serialize listing filters into URLSearchParams. Skips undefined/null
13
+ * values so the URL stays clean. Kept separate from the fetcher so it's
14
+ * testable in isolation.
15
+ */
16
+ export function buildListingFiltersQuery(
17
+ filters: ListingFilters | undefined
18
+ ): URLSearchParams {
19
+ const params = new URLSearchParams();
20
+ if (!filters) return params;
21
+
22
+ if (filters.limit != null) params.set("limit", String(filters.limit));
23
+ if (filters.offset != null) params.set("offset", String(filters.offset));
24
+ if (filters.businessType) params.set("businessType", filters.businessType);
25
+ if (filters.propertyType) params.set("propertyType", filters.propertyType);
26
+ if (filters.city) params.set("city", filters.city);
27
+ if (filters.neighborhood) params.set("neighborhood", filters.neighborhood);
28
+ if (filters.minPrice != null) params.set("minPrice", String(filters.minPrice));
29
+ if (filters.maxPrice != null) params.set("maxPrice", String(filters.maxPrice));
30
+
31
+ return params;
32
+ }
package/src/types.ts ADDED
@@ -0,0 +1,194 @@
1
+ /**
2
+ * Public types for the Garagem Sites SDK.
3
+ *
4
+ * These match the canonical shapes returned by the public Garagem
5
+ * Sites API (`/api/sites/...`). Treat them as the public contract —
6
+ * additive changes only, never breaking.
7
+ */
8
+
9
+ /** Sale/rental indicator. The API may return additional string values; consumers should branch defensively. */
10
+ export type ListingBusinessType = "sale" | "rental" | (string & {});
11
+
12
+ /** Whether the price is shown publicly or kept on request. */
13
+ export type ListingPriceVisibility = "public" | "private";
14
+
15
+ /** Property-level fields shown on a listing summary card. */
16
+ export interface ListingPropertySummary {
17
+ type: string;
18
+ bedrooms: number;
19
+ bathrooms: number;
20
+ suites: number;
21
+ parkingSpaces: number;
22
+ totalArea: number;
23
+ usableArea: number;
24
+ }
25
+
26
+ /** Address breakdown returned with every listing. */
27
+ export interface ListingLocation {
28
+ street: string;
29
+ number: string;
30
+ complement?: string;
31
+ neighborhood: string;
32
+ city: string;
33
+ state: string;
34
+ postalCode: string;
35
+ country?: string;
36
+ coordinates?: {
37
+ lat: number;
38
+ lng: number;
39
+ } | null;
40
+ }
41
+
42
+ /** Single media item attached to a listing (image, video, floor plan, …). */
43
+ export interface ListingMedia {
44
+ id: string;
45
+ type: string;
46
+ category: string;
47
+ src: string;
48
+ alt?: string;
49
+ caption?: string;
50
+ order?: number;
51
+ }
52
+
53
+ /**
54
+ * Minimum information needed to render a listing on a grid or card.
55
+ * Returned by `getListings`.
56
+ *
57
+ * `price` is `null` when the listing's `priceVisibility` is `"private"`
58
+ * (i.e. the price is hidden behind an explicit lead request) or when
59
+ * the underlying record has no price set. Always branch on `price ==
60
+ * null` rather than `!price` so genuine `0` values (rare but legal in
61
+ * promotional flows) don't get masked as "sob consulta".
62
+ */
63
+ export interface Listing {
64
+ id: string;
65
+ title: string;
66
+ description: string;
67
+ businessType: ListingBusinessType;
68
+ price: number | null;
69
+ priceVisibility: ListingPriceVisibility;
70
+ status: string;
71
+ featured: boolean;
72
+ property: ListingPropertySummary;
73
+ location: ListingLocation;
74
+ coverImage?: {
75
+ src: string;
76
+ alt: string;
77
+ } | null;
78
+ createdAt: string;
79
+ updatedAt: string;
80
+ }
81
+
82
+ /**
83
+ * Full listing data including amenities, full media gallery, building
84
+ * details and richer property info. Returned by `getListing`.
85
+ */
86
+ export interface ListingDetail extends Listing {
87
+ amenities: string[];
88
+ tags: string[];
89
+ property: ListingPropertySummary & {
90
+ id: string;
91
+ builtArea?: number;
92
+ landArea?: number;
93
+ floor?: number;
94
+ totalFloors?: number;
95
+ yearBuilt?: number;
96
+ furnished?: boolean;
97
+ petFriendly?: boolean;
98
+ };
99
+ building?: {
100
+ name: string;
101
+ amenities: string[];
102
+ elevators?: number;
103
+ unitsPerFloor?: number;
104
+ totalUnits?: number;
105
+ } | null;
106
+ media: ListingMedia[];
107
+ }
108
+
109
+ /** Filter / pagination options for `getListings`. */
110
+ export interface ListingFilters {
111
+ limit?: number;
112
+ offset?: number;
113
+ businessType?: ListingBusinessType;
114
+ propertyType?: string;
115
+ city?: string;
116
+ neighborhood?: string;
117
+ minPrice?: number;
118
+ maxPrice?: number;
119
+ }
120
+
121
+ /** Wrapped response from `getListings`. */
122
+ export interface ListingsResult {
123
+ listings: Listing[];
124
+ total: number;
125
+ /** Echo of the `limit` query param actually applied (subject to a 100-item cap). */
126
+ limit?: number;
127
+ /** Echo of the `offset` query param actually applied. */
128
+ offset?: number;
129
+ }
130
+
131
+ /**
132
+ * Raw Typesense search parameters accepted by `searchListings`. Mirrors
133
+ * the same body the underlying `/api/sites/{siteId}/search` endpoint
134
+ * forwards to Typesense (`q`, `query_by`, `filter_by`, `sort_by`,
135
+ * `per_page`, `page`, facets, etc.) — see the Typesense docs at
136
+ * https://typesense.org/docs/latest/api/search.html for the full list.
137
+ *
138
+ * This is the SDK's escape hatch when the friendly `getListings` API
139
+ * isn't expressive enough (faceted search, multi-field sort, custom
140
+ * grouping). It's an open dictionary on purpose; the only required
141
+ * field is `q`.
142
+ */
143
+ export interface SearchListingsParams {
144
+ q: string;
145
+ query_by?: string;
146
+ filter_by?: string;
147
+ sort_by?: string;
148
+ per_page?: number;
149
+ page?: number;
150
+ facet_by?: string;
151
+ group_by?: string;
152
+ group_limit?: number;
153
+ /** Any other Typesense param. The SDK passes the whole object through. */
154
+ [key: string]: unknown;
155
+ }
156
+
157
+ /**
158
+ * Raw Typesense response shape — what the backend returns from
159
+ * `multi_search`. Generic over the document type so power users can
160
+ * narrow it in their own codebases without losing access to `hits[].
161
+ * highlight` and `text_match`.
162
+ */
163
+ export interface SearchListingsResult<TDocument = Record<string, unknown>> {
164
+ found: number;
165
+ page: number;
166
+ search_time_ms: number;
167
+ hits: Array<{
168
+ document: TDocument;
169
+ highlight?: Record<string, unknown>;
170
+ text_match?: number;
171
+ }>;
172
+ /** Any other Typesense field. Stays open so we don't break on engine upgrades. */
173
+ [key: string]: unknown;
174
+ }
175
+
176
+ /** Public summary of a Garagem-managed site. Returned by `getSite`. */
177
+ export interface Site {
178
+ id: string;
179
+ name: string;
180
+ domain: string | null;
181
+ tenantId: string;
182
+ }
183
+
184
+ /**
185
+ * App Router caching hints passed straight through to the underlying
186
+ * `fetch` call. See https://nextjs.org/docs/app/api-reference/functions/fetch.
187
+ *
188
+ * Typed loosely so this works in plain Node, Edge, Cloudflare Workers
189
+ * and Bun runtimes without Next-specific types being mandatory.
190
+ */
191
+ export interface RequestNextOptions {
192
+ revalidate?: number | false;
193
+ tags?: string[];
194
+ }