@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.
@@ -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.7.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(url, init);
126
+ const response = await fetchImpl(
127
+ url,
128
+ withPublishableKeyHeader(init, publishableKey)
129
+ );
116
130
  if (!response.ok) {
117
- const text = await response.text().catch(() => "");
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
- constructor(message: string, info: { status: number; url: string }) {
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(url, {
228
- method: "GET",
229
- headers: { Accept: "application/json" },
230
- next,
231
- } as FetchInit);
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 new GaragemSdkError(
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 { createGaragemClient } from "@garagem-ai/site-sdk";
15
- * const garagem = createGaragemClient({ siteId: "abc" });
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
+ }