@garagem-ai/site-sdk 0.7.0 → 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 +169 -28
- package/dist/index.d.mts +178 -4
- package/dist/index.d.ts +178 -4
- package/dist/index.js +538 -32
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +528 -32
- package/dist/index.mjs.map +1 -1
- package/dist/react.d.mts +6 -1
- package/dist/react.d.ts +6 -1
- package/dist/react.js +140 -14
- package/dist/react.js.map +1 -1
- package/dist/react.mjs +140 -14
- package/dist/react.mjs.map +1 -1
- package/dist/{types-photo-search-OeONNDxl.d.mts → types-photo-search-CmGRj6my.d.mts} +25 -0
- package/dist/{types-photo-search-OeONNDxl.d.ts → types-photo-search-CmGRj6my.d.ts} +25 -0
- package/package.json +1 -1
- package/src/client.ts +23 -0
- package/src/fetchers-photos.ts +98 -0
- package/src/fetchers.ts +92 -29
- package/src/index.ts +31 -2
- package/src/internal/sdk-http.ts +122 -0
- package/src/leads.ts +34 -3
- package/src/listing-photos.ts +312 -0
- package/src/react/types.ts +5 -0
- package/src/react/use-public-search.ts +23 -5
- package/src/resolve-site-id.ts +3 -0
- package/src/studio-contract.ts +74 -0
- package/src/types-photos.ts +46 -0
- package/src/types.ts +11 -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.
|
|
@@ -409,6 +420,11 @@ interface BaseOptions {
|
|
|
409
420
|
* understand them.
|
|
410
421
|
*/
|
|
411
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;
|
|
412
428
|
}
|
|
413
429
|
interface GetListingsOptions extends BaseOptions {
|
|
414
430
|
siteId: string;
|
|
@@ -463,9 +479,18 @@ interface GetCmsEntryOptions extends BaseOptions {
|
|
|
463
479
|
declare class GaragemSdkError extends Error {
|
|
464
480
|
readonly status: number;
|
|
465
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;
|
|
466
489
|
constructor(message: string, info: {
|
|
467
490
|
status: number;
|
|
468
491
|
url: string;
|
|
492
|
+
reason?: string | null;
|
|
493
|
+
retryAfter?: number | null;
|
|
469
494
|
});
|
|
470
495
|
}
|
|
471
496
|
/**
|
|
@@ -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.
|
|
@@ -409,6 +420,11 @@ interface BaseOptions {
|
|
|
409
420
|
* understand them.
|
|
410
421
|
*/
|
|
411
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;
|
|
412
428
|
}
|
|
413
429
|
interface GetListingsOptions extends BaseOptions {
|
|
414
430
|
siteId: string;
|
|
@@ -463,9 +479,18 @@ interface GetCmsEntryOptions extends BaseOptions {
|
|
|
463
479
|
declare class GaragemSdkError extends Error {
|
|
464
480
|
readonly status: number;
|
|
465
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;
|
|
466
489
|
constructor(message: string, info: {
|
|
467
490
|
status: number;
|
|
468
491
|
url: string;
|
|
492
|
+
reason?: string | null;
|
|
493
|
+
retryAfter?: number | null;
|
|
469
494
|
});
|
|
470
495
|
}
|
|
471
496
|
/**
|
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",
|
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;
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* "Imóveis com fotos parecidas" fetcher.
|
|
3
|
+
*
|
|
4
|
+
* Self-contained beside `./fetchers`: same base-URL / fetch / `next`
|
|
5
|
+
* conventions, positional ids so a gallery click can call
|
|
6
|
+
* `getSimilarByPhoto(siteId, listing.id, photo.id)` directly.
|
|
7
|
+
*/
|
|
8
|
+
import { callJson, type FetchLike } from "./fetchers";
|
|
9
|
+
import { coerceSiteId, normalizeBaseUrl } from "./internal/url";
|
|
10
|
+
import { listingLookupKey } from "./listing-path";
|
|
11
|
+
import type { RequestNextOptions } from "./types";
|
|
12
|
+
import type { SimilarByPhotoItem, SimilarByPhotoResult } from "./types-photos";
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Loose 8-4-4-4-12 hex, matching the public API's `isUuid(..., "loose")`.
|
|
16
|
+
* `getListing` also emits `image-N` (no UUID in `image_ids`) and `external-N`
|
|
17
|
+
* (video/tour). Those are gallery keys, not media ids.
|
|
18
|
+
*/
|
|
19
|
+
const MEDIA_UUID_RE =
|
|
20
|
+
/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
21
|
+
|
|
22
|
+
const HIDDEN_SIMILAR_PHOTOS: SimilarByPhotoResult = {
|
|
23
|
+
available: false,
|
|
24
|
+
items: [],
|
|
25
|
+
};
|
|
26
|
+
|
|
27
|
+
export interface GetSimilarByPhotoOptions {
|
|
28
|
+
/** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
|
|
29
|
+
baseUrl?: string;
|
|
30
|
+
/** Override the fetch implementation (testing, edge runtimes, retries). */
|
|
31
|
+
fetch?: FetchLike;
|
|
32
|
+
/** Next.js App Router caching hints. Ignored elsewhere. */
|
|
33
|
+
next?: RequestNextOptions;
|
|
34
|
+
/** Max similar listings to return (API default 6, cap 12). */
|
|
35
|
+
limit?: number;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Listings whose public photos look like one photo of `listingId`.
|
|
40
|
+
*
|
|
41
|
+
* `available` is `false` when the site's tenant has no image search, and
|
|
42
|
+
* when `mediaId` is not a media UUID (`image-N`, `external-N`, or any other
|
|
43
|
+
* gallery key `getListing` assigned). That case returns locally, without a
|
|
44
|
+
* request, so a page that passes `photo.id` hides the block instead of
|
|
45
|
+
* throwing. Items carry the public card model plus the photo that matched.
|
|
46
|
+
*
|
|
47
|
+
* @example
|
|
48
|
+
* const { available, items } = await getSimilarByPhoto(
|
|
49
|
+
* siteId,
|
|
50
|
+
* listing.id,
|
|
51
|
+
* photo.id,
|
|
52
|
+
* { limit: 6, next: { revalidate: 300 } }
|
|
53
|
+
* );
|
|
54
|
+
*/
|
|
55
|
+
export async function getSimilarByPhoto(
|
|
56
|
+
siteId: string,
|
|
57
|
+
listingId: string,
|
|
58
|
+
mediaId: string,
|
|
59
|
+
options: GetSimilarByPhotoOptions = {}
|
|
60
|
+
): Promise<SimilarByPhotoResult> {
|
|
61
|
+
const { baseUrl, fetch: fetchImpl, next, limit } = options;
|
|
62
|
+
const resolvedSiteId = await coerceSiteId(siteId);
|
|
63
|
+
const lookupId = listingLookupKey(listingId ?? "");
|
|
64
|
+
if (!lookupId || lookupId === "undefined" || lookupId === "null") {
|
|
65
|
+
throw new TypeError("getSimilarByPhoto: `listingId` is required");
|
|
66
|
+
}
|
|
67
|
+
const photoId = typeof mediaId === "string" ? mediaId.trim() : "";
|
|
68
|
+
if (!photoId) {
|
|
69
|
+
throw new TypeError("getSimilarByPhoto: `mediaId` is required");
|
|
70
|
+
}
|
|
71
|
+
// A synthetic gallery id 400s on the API; `callJson` would throw and the
|
|
72
|
+
// listing page that follows the README would fail instead of hiding.
|
|
73
|
+
if (!MEDIA_UUID_RE.test(photoId)) {
|
|
74
|
+
return HIDDEN_SIMILAR_PHOTOS;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const base = normalizeBaseUrl(baseUrl);
|
|
78
|
+
const params = new URLSearchParams({ mediaId: photoId });
|
|
79
|
+
if (typeof limit === "number" && Number.isFinite(limit) && limit > 0) {
|
|
80
|
+
params.set("limit", String(Math.floor(limit)));
|
|
81
|
+
}
|
|
82
|
+
const url = `${base}/api/sites/${encodeURIComponent(resolvedSiteId)}/listings/${encodeURIComponent(
|
|
83
|
+
lookupId
|
|
84
|
+
)}/similar-photos?${params.toString()}`;
|
|
85
|
+
|
|
86
|
+
const data = await callJson<{
|
|
87
|
+
available?: boolean;
|
|
88
|
+
items?: SimilarByPhotoItem[];
|
|
89
|
+
}>(
|
|
90
|
+
url,
|
|
91
|
+
{ method: "GET", headers: { Accept: "application/json" }, next },
|
|
92
|
+
fetchImpl ?? fetch
|
|
93
|
+
);
|
|
94
|
+
return {
|
|
95
|
+
available: data.available !== false,
|
|
96
|
+
items: Array.isArray(data.items) ? data.items : [],
|
|
97
|
+
};
|
|
98
|
+
}
|
package/src/fetchers.ts
CHANGED
|
@@ -16,6 +16,11 @@ import type {
|
|
|
16
16
|
Site,
|
|
17
17
|
} from "./types";
|
|
18
18
|
import { listingLookupKey } from "./listing-path";
|
|
19
|
+
import {
|
|
20
|
+
parseSdkErrorBody,
|
|
21
|
+
retryAfterFromResponse,
|
|
22
|
+
withPublishableKeyHeader,
|
|
23
|
+
} from "./internal/sdk-http";
|
|
19
24
|
import {
|
|
20
25
|
buildListingFiltersQuery,
|
|
21
26
|
coerceSiteId,
|
|
@@ -36,6 +41,11 @@ interface BaseOptions {
|
|
|
36
41
|
* understand them.
|
|
37
42
|
*/
|
|
38
43
|
next?: RequestNextOptions;
|
|
44
|
+
/**
|
|
45
|
+
* Site publishable key (`pk_live_…`) from Configurações → Sites → API
|
|
46
|
+
* pública. Not a secret. Omit it and the request stays anonymous.
|
|
47
|
+
*/
|
|
48
|
+
publishableKey?: string;
|
|
39
49
|
}
|
|
40
50
|
|
|
41
51
|
export interface GetListingsOptions extends BaseOptions {
|
|
@@ -110,17 +120,15 @@ interface FetchInit extends RequestInit {
|
|
|
110
120
|
export async function callJson<T>(
|
|
111
121
|
url: string,
|
|
112
122
|
init: FetchInit,
|
|
113
|
-
fetchImpl: FetchLike
|
|
123
|
+
fetchImpl: FetchLike,
|
|
124
|
+
publishableKey?: string
|
|
114
125
|
): Promise<T> {
|
|
115
|
-
const response = await fetchImpl(
|
|
126
|
+
const response = await fetchImpl(
|
|
127
|
+
url,
|
|
128
|
+
withPublishableKeyHeader(init, publishableKey)
|
|
129
|
+
);
|
|
116
130
|
if (!response.ok) {
|
|
117
|
-
|
|
118
|
-
throw new GaragemSdkError(
|
|
119
|
-
`Garagem SDK: request failed (${response.status} ${response.statusText}) for ${url}${
|
|
120
|
-
text ? ` — ${text.slice(0, 200)}` : ""
|
|
121
|
-
}`,
|
|
122
|
-
{ status: response.status, url }
|
|
123
|
-
);
|
|
131
|
+
throw await readGaragemSdkError(response, url);
|
|
124
132
|
}
|
|
125
133
|
return (await response.json()) as T;
|
|
126
134
|
}
|
|
@@ -129,14 +137,56 @@ export async function callJson<T>(
|
|
|
129
137
|
export class GaragemSdkError extends Error {
|
|
130
138
|
readonly status: number;
|
|
131
139
|
readonly url: string;
|
|
132
|
-
|
|
140
|
+
/** Machine reason from the JSON body (`invalid_publishable_key`, `rate_limited`, …). */
|
|
141
|
+
readonly reason: string | null;
|
|
142
|
+
/**
|
|
143
|
+
* Seconds to wait before retrying. Set on HTTP 429 from `Retry-After`
|
|
144
|
+
* or the body's `retryAfterSeconds`. `null` when the response has neither.
|
|
145
|
+
*/
|
|
146
|
+
readonly retryAfter: number | null;
|
|
147
|
+
constructor(
|
|
148
|
+
message: string,
|
|
149
|
+
info: {
|
|
150
|
+
status: number;
|
|
151
|
+
url: string;
|
|
152
|
+
reason?: string | null;
|
|
153
|
+
retryAfter?: number | null;
|
|
154
|
+
}
|
|
155
|
+
) {
|
|
133
156
|
super(message);
|
|
134
157
|
this.name = "GaragemSdkError";
|
|
135
158
|
this.status = info.status;
|
|
136
159
|
this.url = info.url;
|
|
160
|
+
this.reason = info.reason ?? null;
|
|
161
|
+
this.retryAfter = info.retryAfter ?? null;
|
|
137
162
|
}
|
|
138
163
|
}
|
|
139
164
|
|
|
165
|
+
/** Build a {@link GaragemSdkError} from a non-2xx response (reads the body). */
|
|
166
|
+
export async function readGaragemSdkError(
|
|
167
|
+
response: Response,
|
|
168
|
+
url: string
|
|
169
|
+
): Promise<GaragemSdkError> {
|
|
170
|
+
const text = await response.text().catch(() => "");
|
|
171
|
+
const parsed = parseSdkErrorBody(text);
|
|
172
|
+
const retryAfter =
|
|
173
|
+
response.status === 429
|
|
174
|
+
? retryAfterFromResponse(response, parsed.retryAfterSeconds)
|
|
175
|
+
: parsed.retryAfterSeconds;
|
|
176
|
+
const detail = parsed.summary;
|
|
177
|
+
return new GaragemSdkError(
|
|
178
|
+
`Garagem SDK: request failed (${response.status} ${response.statusText}) for ${url}${
|
|
179
|
+
detail ? ` — ${detail}` : ""
|
|
180
|
+
}`,
|
|
181
|
+
{
|
|
182
|
+
status: response.status,
|
|
183
|
+
url,
|
|
184
|
+
reason: parsed.reason,
|
|
185
|
+
retryAfter,
|
|
186
|
+
}
|
|
187
|
+
);
|
|
188
|
+
}
|
|
189
|
+
|
|
140
190
|
/**
|
|
141
191
|
* Fetch a paginated list of listings for a given site.
|
|
142
192
|
*
|
|
@@ -160,7 +210,8 @@ export async function getListings(
|
|
|
160
210
|
const data = await callJson<{ listings?: Listing[]; total?: number }>(
|
|
161
211
|
url,
|
|
162
212
|
{ method: "GET", headers: { Accept: "application/json" }, next },
|
|
163
|
-
fetchImpl ?? fetch
|
|
213
|
+
fetchImpl ?? fetch,
|
|
214
|
+
options.publishableKey
|
|
164
215
|
);
|
|
165
216
|
return {
|
|
166
217
|
listings: data.listings ?? [],
|
|
@@ -189,7 +240,8 @@ export async function getListing(
|
|
|
189
240
|
return callJson<ListingDetail>(
|
|
190
241
|
url,
|
|
191
242
|
{ method: "GET", headers: { Accept: "application/json" }, next },
|
|
192
|
-
fetchImpl ?? fetch
|
|
243
|
+
fetchImpl ?? fetch,
|
|
244
|
+
options.publishableKey
|
|
193
245
|
);
|
|
194
246
|
}
|
|
195
247
|
|
|
@@ -224,17 +276,20 @@ export async function getSite(options: GetSiteOptions): Promise<Site | null> {
|
|
|
224
276
|
const url = `${base}/api/sites/resolve?${params.toString()}`;
|
|
225
277
|
|
|
226
278
|
const f = fetchImpl ?? fetch;
|
|
227
|
-
const response = await f(
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
279
|
+
const response = await f(
|
|
280
|
+
url,
|
|
281
|
+
withPublishableKeyHeader(
|
|
282
|
+
{
|
|
283
|
+
method: "GET",
|
|
284
|
+
headers: { Accept: "application/json" },
|
|
285
|
+
next,
|
|
286
|
+
},
|
|
287
|
+
options.publishableKey
|
|
288
|
+
) as FetchInit
|
|
289
|
+
);
|
|
232
290
|
if (response.status === 404) return null;
|
|
233
291
|
if (!response.ok) {
|
|
234
|
-
throw
|
|
235
|
-
`Garagem SDK: getSite failed (${response.status}) for ${url}`,
|
|
236
|
-
{ status: response.status, url }
|
|
237
|
-
);
|
|
292
|
+
throw await readGaragemSdkError(response, url);
|
|
238
293
|
}
|
|
239
294
|
const data = (await response.json()) as {
|
|
240
295
|
id: string;
|
|
@@ -295,7 +350,8 @@ export async function searchListings<TDocument = Record<string, unknown>>(
|
|
|
295
350
|
body: JSON.stringify(params),
|
|
296
351
|
next,
|
|
297
352
|
},
|
|
298
|
-
fetchImpl ?? fetch
|
|
353
|
+
fetchImpl ?? fetch,
|
|
354
|
+
options.publishableKey
|
|
299
355
|
);
|
|
300
356
|
}
|
|
301
357
|
|
|
@@ -313,7 +369,8 @@ export async function getSearchUi(
|
|
|
313
369
|
return callJson<SearchUi>(
|
|
314
370
|
url,
|
|
315
371
|
{ method: "GET", headers: { Accept: "application/json" }, next },
|
|
316
|
-
fetchImpl ?? fetch
|
|
372
|
+
fetchImpl ?? fetch,
|
|
373
|
+
options.publishableKey
|
|
317
374
|
);
|
|
318
375
|
}
|
|
319
376
|
|
|
@@ -339,7 +396,8 @@ export async function queryListings(
|
|
|
339
396
|
body: JSON.stringify(params ?? {}),
|
|
340
397
|
next,
|
|
341
398
|
},
|
|
342
|
-
fetchImpl ?? fetch
|
|
399
|
+
fetchImpl ?? fetch,
|
|
400
|
+
options.publishableKey
|
|
343
401
|
);
|
|
344
402
|
}
|
|
345
403
|
|
|
@@ -375,7 +433,8 @@ export async function getSimilarListings(
|
|
|
375
433
|
const data = await callJson<{ listings?: Listing[]; total?: number }>(
|
|
376
434
|
url,
|
|
377
435
|
{ method: "GET", headers: { Accept: "application/json" }, next },
|
|
378
|
-
fetchImpl ?? fetch
|
|
436
|
+
fetchImpl ?? fetch,
|
|
437
|
+
options.publishableKey
|
|
379
438
|
);
|
|
380
439
|
return {
|
|
381
440
|
listings: data.listings ?? [],
|
|
@@ -394,7 +453,8 @@ export async function getCmsCollections(
|
|
|
394
453
|
const data = await callJson<{ collections?: CmsCollection[] }>(
|
|
395
454
|
url,
|
|
396
455
|
{ method: "GET", headers: { Accept: "application/json" }, next },
|
|
397
|
-
fetchImpl ?? fetch
|
|
456
|
+
fetchImpl ?? fetch,
|
|
457
|
+
options.publishableKey
|
|
398
458
|
);
|
|
399
459
|
return data.collections ?? [];
|
|
400
460
|
}
|
|
@@ -415,7 +475,8 @@ export async function getCmsCollection(
|
|
|
415
475
|
const data = await callJson<{ collection?: CmsCollection } | CmsCollection>(
|
|
416
476
|
url,
|
|
417
477
|
{ method: "GET", headers: { Accept: "application/json" }, next },
|
|
418
|
-
fetchImpl ?? fetch
|
|
478
|
+
fetchImpl ?? fetch,
|
|
479
|
+
options.publishableKey
|
|
419
480
|
);
|
|
420
481
|
if (
|
|
421
482
|
data &&
|
|
@@ -460,7 +521,8 @@ export async function getCmsEntries(
|
|
|
460
521
|
const data = await callJson<Partial<CmsEntriesResult>>(
|
|
461
522
|
url,
|
|
462
523
|
{ method: "GET", headers: { Accept: "application/json" }, next },
|
|
463
|
-
fetchImpl ?? fetch
|
|
524
|
+
fetchImpl ?? fetch,
|
|
525
|
+
options.publishableKey
|
|
464
526
|
);
|
|
465
527
|
return {
|
|
466
528
|
entries: data.entries ?? [],
|
|
@@ -489,7 +551,8 @@ export async function getCmsEntry(
|
|
|
489
551
|
const data = await callJson<{ entry?: CmsEntry } | CmsEntry>(
|
|
490
552
|
url,
|
|
491
553
|
{ method: "GET", headers: { Accept: "application/json" }, next },
|
|
492
|
-
fetchImpl ?? fetch
|
|
554
|
+
fetchImpl ?? fetch,
|
|
555
|
+
options.publishableKey
|
|
493
556
|
);
|
|
494
557
|
if (data && typeof data === "object" && "entry" in data && data.entry) {
|
|
495
558
|
return data.entry;
|
package/src/index.ts
CHANGED
|
@@ -11,8 +11,8 @@
|
|
|
11
11
|
*
|
|
12
12
|
* 2. Client object (binds defaults):
|
|
13
13
|
*
|
|
14
|
-
* import {
|
|
15
|
-
* const garagem =
|
|
14
|
+
* import { createClient } from "@garagem-ai/site-sdk";
|
|
15
|
+
* const garagem = createClient({ siteId: "abc", publishableKey: "pk_live_…" });
|
|
16
16
|
* const { listings } = await garagem.getListings();
|
|
17
17
|
*
|
|
18
18
|
* Works in Node, Edge runtimes, Cloudflare Workers, Bun, Deno and the
|
|
@@ -257,8 +257,11 @@ export {
|
|
|
257
257
|
studioLeadInstruction,
|
|
258
258
|
studioListingCardInstruction,
|
|
259
259
|
studioListingDetailInstruction,
|
|
260
|
+
studioPhotoInstruction,
|
|
261
|
+
studioPhotoInstructionFor,
|
|
260
262
|
studioSearchInstruction,
|
|
261
263
|
studioSearchLandmarkInstruction,
|
|
264
|
+
studioPublishableKeyInstruction,
|
|
262
265
|
studioPhotoSearchInstruction,
|
|
263
266
|
isPhotoSearchOnPin,
|
|
264
267
|
studioSdkPinInstruction,
|
|
@@ -269,11 +272,37 @@ export {
|
|
|
269
272
|
} from "./studio-contract";
|
|
270
273
|
|
|
271
274
|
export {
|
|
275
|
+
createClient,
|
|
272
276
|
createGaragemClient,
|
|
273
277
|
type CreateGaragemClientOptions,
|
|
274
278
|
type GaragemClient,
|
|
275
279
|
} from "./client";
|
|
276
280
|
|
|
281
|
+
// ---------------------------------------------------------------------------
|
|
282
|
+
// Photo intelligence: captions / room groups on `ListingDetail.media` and
|
|
283
|
+
// "imóveis com fotos parecidas" (`getSimilarByPhoto`). Self-contained block.
|
|
284
|
+
// ---------------------------------------------------------------------------
|
|
285
|
+
export type {
|
|
286
|
+
ListingPhotoGroup,
|
|
287
|
+
SimilarByPhotoItem,
|
|
288
|
+
SimilarByPhotoResult,
|
|
289
|
+
SimilarPhotoMatch,
|
|
290
|
+
} from "./types-photos";
|
|
291
|
+
|
|
292
|
+
export {
|
|
293
|
+
getSimilarByPhoto,
|
|
294
|
+
type GetSimilarByPhotoOptions,
|
|
295
|
+
} from "./fetchers-photos";
|
|
296
|
+
|
|
297
|
+
export {
|
|
298
|
+
PHOTO_GROUP_OTHER_KEY,
|
|
299
|
+
PHOTO_GROUP_OTHER_LABEL,
|
|
300
|
+
listingPhotoGroups,
|
|
301
|
+
listingVisualHighlights,
|
|
302
|
+
photoRoomLabel,
|
|
303
|
+
type ListingVisualHighlightsOptions,
|
|
304
|
+
} from "./listing-photos";
|
|
305
|
+
|
|
277
306
|
// ---------------------------------------------------------------------------
|
|
278
307
|
// Market data (requires the IPTU module — `iptu_itbi_integration`).
|
|
279
308
|
// Self-contained block: fetchers, headless pt-BR labels and types. Every
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Publishable-key header and error parsing shared by the SDK fetchers.
|
|
3
|
+
*
|
|
4
|
+
* The key is an identifier (`pk_live_…`), not a secret. Foundation accepts
|
|
5
|
+
* it as `X-Garagem-Publishable-Key` or `Authorization: Bearer pk_live_…`.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
export const PUBLISHABLE_KEY_HEADER = "X-Garagem-Publishable-Key";
|
|
9
|
+
|
|
10
|
+
export function publishableKeyHeaders(
|
|
11
|
+
publishableKey?: string | null
|
|
12
|
+
): Record<string, string> {
|
|
13
|
+
const key = publishableKey?.trim();
|
|
14
|
+
if (!key) return {};
|
|
15
|
+
return { [PUBLISHABLE_KEY_HEADER]: key };
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** Merge the publishable-key header into a plain-object `fetch` init. */
|
|
19
|
+
export function withPublishableKeyHeader<T extends { headers?: HeadersInit }>(
|
|
20
|
+
init: T,
|
|
21
|
+
publishableKey?: string | null
|
|
22
|
+
): T {
|
|
23
|
+
const extra = publishableKeyHeaders(publishableKey);
|
|
24
|
+
if (Object.keys(extra).length === 0) return init;
|
|
25
|
+
const current = init.headers;
|
|
26
|
+
const base = plainHeaders(current);
|
|
27
|
+
return { ...init, headers: { ...base, ...extra } };
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function plainHeaders(
|
|
31
|
+
headers: HeadersInit | undefined
|
|
32
|
+
): Record<string, string> {
|
|
33
|
+
const out: Record<string, string> = {};
|
|
34
|
+
if (!headers) return out;
|
|
35
|
+
if (typeof Headers !== "undefined" && headers instanceof Headers) {
|
|
36
|
+
headers.forEach((value, name) => {
|
|
37
|
+
out[name] = value;
|
|
38
|
+
});
|
|
39
|
+
return out;
|
|
40
|
+
}
|
|
41
|
+
if (Array.isArray(headers)) {
|
|
42
|
+
for (const pair of headers) {
|
|
43
|
+
out[String(pair[0])] = String(pair[1]);
|
|
44
|
+
}
|
|
45
|
+
return out;
|
|
46
|
+
}
|
|
47
|
+
// `HeadersInit` stays a union after the class/array checks in some lib
|
|
48
|
+
// targets. Copy string entries only so the result is always a plain record.
|
|
49
|
+
for (const [name, value] of Object.entries(
|
|
50
|
+
headers as Record<string, unknown>
|
|
51
|
+
)) {
|
|
52
|
+
if (typeof value === "string") out[name] = value;
|
|
53
|
+
}
|
|
54
|
+
return out;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export interface ParsedSdkErrorBody {
|
|
58
|
+
reason: string | null;
|
|
59
|
+
retryAfterSeconds: number | null;
|
|
60
|
+
/** Short human text from `error` or the raw body. */
|
|
61
|
+
summary: string;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function finiteNonNegative(value: unknown): number | null {
|
|
65
|
+
if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
|
|
66
|
+
return value;
|
|
67
|
+
}
|
|
68
|
+
if (typeof value === "string" && value.trim()) {
|
|
69
|
+
const parsed = Number(value);
|
|
70
|
+
if (Number.isFinite(parsed) && parsed >= 0) return parsed;
|
|
71
|
+
}
|
|
72
|
+
return null;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
export function parseSdkErrorBody(text: string): ParsedSdkErrorBody {
|
|
76
|
+
const raw = text ? text.slice(0, 200) : "";
|
|
77
|
+
if (!text) {
|
|
78
|
+
return { reason: null, retryAfterSeconds: null, summary: "" };
|
|
79
|
+
}
|
|
80
|
+
try {
|
|
81
|
+
const body = JSON.parse(text) as unknown;
|
|
82
|
+
if (!body || typeof body !== "object") {
|
|
83
|
+
return { reason: null, retryAfterSeconds: null, summary: raw };
|
|
84
|
+
}
|
|
85
|
+
const record = body as Record<string, unknown>;
|
|
86
|
+
const reason =
|
|
87
|
+
typeof record.reason === "string" && record.reason ? record.reason : null;
|
|
88
|
+
const retryAfterSeconds = finiteNonNegative(
|
|
89
|
+
record.retryAfterSeconds ?? record.retryAfter
|
|
90
|
+
);
|
|
91
|
+
const errorText =
|
|
92
|
+
typeof record.error === "string" && record.error ? record.error : raw;
|
|
93
|
+
return {
|
|
94
|
+
reason,
|
|
95
|
+
retryAfterSeconds,
|
|
96
|
+
summary: errorText.slice(0, 200),
|
|
97
|
+
};
|
|
98
|
+
} catch {
|
|
99
|
+
return { reason: null, retryAfterSeconds: null, summary: raw };
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Seconds the caller should wait. The `Retry-After` header wins (delta
|
|
105
|
+
* seconds, or an HTTP date). Otherwise the JSON `retryAfterSeconds`.
|
|
106
|
+
*/
|
|
107
|
+
export function retryAfterFromResponse(
|
|
108
|
+
response: { headers: { get(name: string): string | null } },
|
|
109
|
+
bodySeconds: number | null,
|
|
110
|
+
nowMs: number = Date.now()
|
|
111
|
+
): number | null {
|
|
112
|
+
const header = response.headers.get("Retry-After")?.trim();
|
|
113
|
+
if (header) {
|
|
114
|
+
const delta = finiteNonNegative(header);
|
|
115
|
+
if (delta != null) return delta;
|
|
116
|
+
const at = Date.parse(header);
|
|
117
|
+
if (Number.isFinite(at)) {
|
|
118
|
+
return Math.max(0, Math.ceil((at - nowMs) / 1000));
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
return bodySeconds;
|
|
122
|
+
}
|