@garagem-ai/site-sdk 0.11.0 → 0.12.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 +1 -0
- package/dist/index.d.mts +166 -5
- package/dist/index.d.ts +166 -5
- package/dist/index.js +88 -6
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +85 -6
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
- package/src/index.ts +14 -0
- package/src/share.ts +114 -0
- package/src/studio-contract.ts +62 -8
- package/src/types-share.ts +122 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@garagem-ai/site-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.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/index.ts
CHANGED
|
@@ -82,6 +82,18 @@ export {
|
|
|
82
82
|
type SearchListingsOptions,
|
|
83
83
|
} from "./fetchers";
|
|
84
84
|
|
|
85
|
+
export { getShareLink, type GetShareLinkOptions } from "./share";
|
|
86
|
+
|
|
87
|
+
export type {
|
|
88
|
+
ShareEntityType,
|
|
89
|
+
ShareLinkError,
|
|
90
|
+
ShareLinkErrorReason,
|
|
91
|
+
ShareLinkResult,
|
|
92
|
+
ShareLinkSuccess,
|
|
93
|
+
ShareLinkToken,
|
|
94
|
+
ShareListingEntity,
|
|
95
|
+
} from "./types-share";
|
|
96
|
+
|
|
85
97
|
export {
|
|
86
98
|
STUDIO_DEFAULT_VISIT_SCHEDULE,
|
|
87
99
|
VISIT_TIME_ZONE,
|
|
@@ -286,7 +298,9 @@ export {
|
|
|
286
298
|
studioPhotoSearchInstruction,
|
|
287
299
|
isPhotoSearchOnPin,
|
|
288
300
|
isSellerLeadOnPin,
|
|
301
|
+
isShareLinkOnPin,
|
|
289
302
|
studioSellerLeadSdkInstruction,
|
|
303
|
+
studioShareLinkInstruction,
|
|
290
304
|
studioSdkPinInstruction,
|
|
291
305
|
studioSiteWidthCss,
|
|
292
306
|
hasShowcaseLeadsPostUrl,
|
package/src/share.ts
ADDED
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
import type { RequestNextOptions } from "./types";
|
|
2
|
+
import type { ShareLinkResult } from "./types-share";
|
|
3
|
+
import { withPublishableKeyHeader } from "./internal/sdk-http";
|
|
4
|
+
import { normalizeBaseUrl } from "./internal/url";
|
|
5
|
+
import { GaragemSdkError, type FetchLike } from "./fetchers";
|
|
6
|
+
|
|
7
|
+
export interface GetShareLinkOptions {
|
|
8
|
+
/** The `{token}` from a `/p/{token}` (or `/s`, `/i`, `/r`, `/c`) URL. */
|
|
9
|
+
token: string;
|
|
10
|
+
/** Password for a password-protected share. Sends a POST when present,
|
|
11
|
+
* a GET otherwise — matches the Foundation route's contract. */
|
|
12
|
+
password?: string;
|
|
13
|
+
/** Garagem API base URL. Defaults to `https://app.garagem.ai`. */
|
|
14
|
+
baseUrl?: string;
|
|
15
|
+
/** Override the fetch implementation (testing, edge runtimes, retries). */
|
|
16
|
+
fetch?: FetchLike;
|
|
17
|
+
/** Next.js App Router caching hints. Ignored on runtimes that don't
|
|
18
|
+
* understand them. Share links are per-visitor and often
|
|
19
|
+
* password/expiry-gated — avoid caching this call in production unless
|
|
20
|
+
* you know the token is long-lived and public. */
|
|
21
|
+
next?: RequestNextOptions;
|
|
22
|
+
/**
|
|
23
|
+
* Site publishable key (`pk_live_…`) from Configurações → Sites → API
|
|
24
|
+
* pública. Not a secret. Omit it and the request stays anonymous.
|
|
25
|
+
*/
|
|
26
|
+
publishableKey?: string;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
interface RawShareErrorBody {
|
|
30
|
+
error?: string;
|
|
31
|
+
reason?: string;
|
|
32
|
+
listingCode?: string;
|
|
33
|
+
site?: Record<string, unknown>;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
interface ShareFetchInit extends RequestInit {
|
|
37
|
+
next?: RequestNextOptions;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Resolve a share-link token (`/p/{token}` and friends) against Foundation's
|
|
42
|
+
* public share-link API.
|
|
43
|
+
*
|
|
44
|
+
* Unlike {@link import("./fetchers").getListing}, this does **not** throw on
|
|
45
|
+
* a 401/403/404/410 — those are expected, UI-relevant outcomes for a share
|
|
46
|
+
* page (password gate, expired link, not found), returned as
|
|
47
|
+
* `{ ok: false, reason, ... }` so the caller can branch instead of catching.
|
|
48
|
+
* Genuine transport/5xx failures still throw {@link GaragemSdkError}.
|
|
49
|
+
*
|
|
50
|
+
* @example
|
|
51
|
+
* const result = await getShareLink({ token });
|
|
52
|
+
* if (!result.ok && result.reason === "password_required") {
|
|
53
|
+
* // render a password form, then retry with `password`
|
|
54
|
+
* }
|
|
55
|
+
* if (!result.ok) {
|
|
56
|
+
* // "not_found" | "inactive" | "expired" | other -> not-available state
|
|
57
|
+
* }
|
|
58
|
+
* // result.ok === true: result.entity (today's raw shape — see
|
|
59
|
+
* // types-share.ts doc for the planned normalized `listing` field)
|
|
60
|
+
*/
|
|
61
|
+
export async function getShareLink(
|
|
62
|
+
options: GetShareLinkOptions
|
|
63
|
+
): Promise<ShareLinkResult> {
|
|
64
|
+
const { token, password, baseUrl, fetch: fetchImpl, next } = options;
|
|
65
|
+
if (!token || !token.trim()) {
|
|
66
|
+
throw new TypeError("getShareLink: `token` is required");
|
|
67
|
+
}
|
|
68
|
+
const base = normalizeBaseUrl(baseUrl);
|
|
69
|
+
const url = `${base}/api/sites/share/${encodeURIComponent(token)}`;
|
|
70
|
+
const doFetch = fetchImpl ?? fetch;
|
|
71
|
+
|
|
72
|
+
const baseInit: ShareFetchInit = password
|
|
73
|
+
? {
|
|
74
|
+
method: "POST",
|
|
75
|
+
headers: {
|
|
76
|
+
Accept: "application/json",
|
|
77
|
+
"Content-Type": "application/json",
|
|
78
|
+
},
|
|
79
|
+
body: JSON.stringify({ password }),
|
|
80
|
+
next,
|
|
81
|
+
}
|
|
82
|
+
: { method: "GET", headers: { Accept: "application/json" }, next };
|
|
83
|
+
|
|
84
|
+
const init = withPublishableKeyHeader(baseInit, options.publishableKey);
|
|
85
|
+
|
|
86
|
+
const response = await doFetch(url, init);
|
|
87
|
+
|
|
88
|
+
if (response.ok) {
|
|
89
|
+
return { ok: true, ...(await response.json()) } as ShareLinkResult;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
// Foundation's own "this token is bad" responses (404/410/401/403) are
|
|
93
|
+
// well-formed JSON errors, not transport failures — surface them as data.
|
|
94
|
+
const EXPECTED_STATUSES = new Set([400, 401, 403, 404, 410]);
|
|
95
|
+
if (EXPECTED_STATUSES.has(response.status)) {
|
|
96
|
+
const body = (await response.json().catch(() => ({}))) as RawShareErrorBody;
|
|
97
|
+
return {
|
|
98
|
+
ok: false,
|
|
99
|
+
status: response.status,
|
|
100
|
+
reason: body.reason ?? null,
|
|
101
|
+
message: body.error ?? "Share link unavailable",
|
|
102
|
+
...(body.listingCode ? { listingCode: body.listingCode } : {}),
|
|
103
|
+
...(body.site ? { site: body.site } : {}),
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
const text = await response.text().catch(() => "");
|
|
108
|
+
throw new GaragemSdkError(
|
|
109
|
+
`Garagem SDK: request failed (${response.status} ${response.statusText}) for ${url}${
|
|
110
|
+
text ? ` — ${text.slice(0, 200)}` : ""
|
|
111
|
+
}`,
|
|
112
|
+
{ status: response.status, url }
|
|
113
|
+
);
|
|
114
|
+
}
|
package/src/studio-contract.ts
CHANGED
|
@@ -23,10 +23,11 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
23
23
|
* Phone mask helpers shipped in 0.6.0. Map search
|
|
24
24
|
* (`useMapSearch`, `searchListingsInBounds`) shipped in 0.9.0 — 0.7.0
|
|
25
25
|
* does not export them. Property registration shipped in 0.10.0.
|
|
26
|
-
*
|
|
27
|
-
*
|
|
26
|
+
* Weighted map buckets (`map.buckets`, clustered by the hook) shipped
|
|
27
|
+
* in 0.11.0. Search filter helpers (`visibleSearchFilters` /
|
|
28
|
+
* `toolbarFilterIds`) shipped in 0.4.12 and remain on this pin.
|
|
28
29
|
*/
|
|
29
|
-
minNpmVersion: "0.
|
|
30
|
+
minNpmVersion: "0.11.0",
|
|
30
31
|
/** Historical: older tarballs inject card CSS when those components mount. */
|
|
31
32
|
selfInjectSince: "0.4.2",
|
|
32
33
|
chromeStrategy: "app-owned" as const,
|
|
@@ -226,6 +227,14 @@ export const STUDIO_SDK_CONTRACT = {
|
|
|
226
227
|
"isValidName",
|
|
227
228
|
] as const,
|
|
228
229
|
sellerLeadSince: "0.10.0",
|
|
230
|
+
/**
|
|
231
|
+
* Share-link page (`/p/[token]`). Prompt-safe only once `minNpmVersion`
|
|
232
|
+
* reaches `shareLinkSince`. Below it `studioShareLinkInstruction` prints
|
|
233
|
+
* nothing and `studioCodegenContractViolations` flags `getShareLink` —
|
|
234
|
+
* v0 installs the pin and copies any identifier it sees.
|
|
235
|
+
*/
|
|
236
|
+
shareExports: ["getShareLink"] as const,
|
|
237
|
+
shareLinkSince: "0.12.0",
|
|
229
238
|
} as const;
|
|
230
239
|
|
|
231
240
|
export type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
|
|
@@ -237,6 +246,25 @@ export function isSellerLeadOnPin(
|
|
|
237
246
|
return compareSemver(pin, STUDIO_SDK_CONTRACT.sellerLeadSince) >= 0;
|
|
238
247
|
}
|
|
239
248
|
|
|
249
|
+
/** Whether the pinned tarball exports `getShareLink`. */
|
|
250
|
+
export function isShareLinkOnPin(
|
|
251
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
252
|
+
): boolean {
|
|
253
|
+
return compareSemver(pin, STUDIO_SDK_CONTRACT.shareLinkSince) >= 0;
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/**
|
|
257
|
+
* Native `/p/[token]` page. Empty below `shareLinkSince`, so the current
|
|
258
|
+
* Studio prompt does not mention `getShareLink`.
|
|
259
|
+
*/
|
|
260
|
+
export function studioShareLinkInstruction(
|
|
261
|
+
pin: string = STUDIO_SDK_CONTRACT.minNpmVersion
|
|
262
|
+
): string {
|
|
263
|
+
if (!isShareLinkOnPin(pin)) return "";
|
|
264
|
+
const name = STUDIO_SDK_CONTRACT.shareExports[0];
|
|
265
|
+
return `Share links (\`/p/[token]\`): add a server page \`app/p/[token]/page.tsx\`. Read \`token\` from the route params and \`const result = await ${name}({ token, baseUrl: GARAGEM_API_BASE })\`. When \`result.ok\` is false and \`result.reason\` is \`password_required\` or \`password_invalid\`, render a password form and submit \`getShareLink({ token, password, baseUrl: GARAGEM_API_BASE })\`. For \`not_found\`, \`inactive\`, or \`expired\`, say the link is no longer available — do not render a generic framework 404. When \`result.ok\` and \`result.listing\` is set, render that listing with the same listing-detail module \`/imoveis\` already uses (\`listingDetailModel\` and the site gallery). Do not invent a second listing layout and do not proxy the page to another host.`;
|
|
266
|
+
}
|
|
267
|
+
|
|
240
268
|
/**
|
|
241
269
|
* Fixed SDK half of the property-registration page. The configured fields
|
|
242
270
|
* and photo options come from the Studio onboarding block. Empty below
|
|
@@ -460,6 +488,23 @@ export function studioMapsInstruction(options: { pin?: string } = {}): string {
|
|
|
460
488
|
return `Maps on listing detail: from \`${STUDIO_SDK_PACKAGE}\` import ${names}. \`listing.location.coordinates\` is already masked by the site's privacy settings (≈100 m by default) — pass the listing object as-is; never un-mask, never re-geocode the street address to get a sharper point, never add decimals (\`maxDecimals\` can only coarsen). Always pass \`siteId\` (the resolved site id / publishable key) so maps.fndn.ai meters the site. Static map: \`const mapSrc = listingStaticMapUrl(listing, { width: 640, height: 320, zoom: 15, style: "roadmap", siteId })\` then \`{mapSrc ? <img src={mapSrc} alt={model.location.label} /> : null}\` — \`null\` means no coordinates, so omit the block (never a placeholder image). Zoom is capped by the coordinate precision (16 on the default mask); do not work around it. Street View: on the server page \`const sv = await listingStreetViewAvailable(listing, { siteId })\` (metadata is free), and only when \`sv.available\` render \`<img src={listingStreetViewUrl(listing, { width: 640, height: 400, siteId })} alt="Street View" />\` — the image is billed per load. Neighbourhood outline on an interactive map: load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` (never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`); in \`initMap\` do \`const outline = await neighborhoodBoundaryLayer(listing.location.city, listing.location.neighborhood, { siteId })\` and \`if (outline.feature) map.data.addGeoJson(outline.feature)\`; with MapLibre the vector source url is \`boundaryLayerUrl(listing.location.city)\`. Travel time (“quanto tempo até…”): \`const trip = await travelTimeFromListing(listing, destination, { mode: "driving", siteId })\` gives \`{ minutes, distanceKm }\` or \`null\` (hide the row). Every uncached call is a billed Google Directions request: call it on demand — a destination the visitor typed, or at most one fixed landmark per listing page — never per listing card, never inside a search loop, keep the SDK cache on (default 15 min LRU, \`cache: null\` only in tests), and do not re-run it on every render.`;
|
|
461
489
|
}
|
|
462
490
|
|
|
491
|
+
const MAP_CLUSTER_MEMBERS_CLICK =
|
|
492
|
+
"`const members = map.pins.filter((pin) => cluster.pinIds.includes(pin.id))`, then `fitBounds` a LatLngBounds of their coordinates with about 64px padding, so the listings land inside the new view and split into chips.";
|
|
493
|
+
const MAP_CLUSTER_SAME_POINT =
|
|
494
|
+
"When every member has the same coordinates, or the map is already at zoom 18, do not zoom: open a small list of those listings, each with its price and a link.";
|
|
495
|
+
|
|
496
|
+
/**
|
|
497
|
+
* Cluster click recipe. From `mapBucketsSince` on, a cluster with empty
|
|
498
|
+
* `pinIds` is a weighted bucket with no members to fit, so the members
|
|
499
|
+
* recipe and the bucket recipe must each name the clusters they cover.
|
|
500
|
+
*/
|
|
501
|
+
function studioMapClusterClickInstruction(buckets: boolean): string {
|
|
502
|
+
if (!buckets) {
|
|
503
|
+
return `Clicking a cluster opens its members: ${MAP_CLUSTER_MEMBERS_CLICK} Do not step the zoom around \`cluster.lat\`/\`cluster.lng\`: that point is approximate and the area around it can come back empty. ${MAP_CLUSTER_SAME_POINT}`;
|
|
504
|
+
}
|
|
505
|
+
return `Clicking a cluster depends on \`cluster.pinIds\`. A cluster with members (\`cluster.pinIds.length > 0\`) opens them: ${MAP_CLUSTER_MEMBERS_CLICK} For such a cluster do not step the zoom around \`cluster.lat\`/\`cluster.lng\`: that point is approximate and the area around it can come back empty. ${MAP_CLUSTER_SAME_POINT} A cluster with empty \`pinIds\` is a bucket and has no members to fit: on click center the map on \`cluster.lat\`/\`cluster.lng\` and zoom in two levels — the next viewport search returns finer buckets or the listings themselves.`;
|
|
506
|
+
}
|
|
507
|
+
|
|
463
508
|
/**
|
|
464
509
|
* Search-page map mode. Empty below `mapsSince`. Studio injects this only
|
|
465
510
|
* when the site chose list and map. Listing-detail helpers stay out of it.
|
|
@@ -469,11 +514,13 @@ export function studioMapSearchInstruction(
|
|
|
469
514
|
): string {
|
|
470
515
|
if (!mapsExportsPublished(options.pin)) return "";
|
|
471
516
|
const pin = options.pin ?? STUDIO_SDK_CONTRACT.minNpmVersion;
|
|
472
|
-
const
|
|
473
|
-
compareSemver(pin, STUDIO_SDK_CONTRACT.mapBucketsSince) >= 0
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
517
|
+
const hasBuckets =
|
|
518
|
+
compareSemver(pin, STUDIO_SDK_CONTRACT.mapBucketsSince) >= 0;
|
|
519
|
+
const buckets = hasBuckets
|
|
520
|
+
? " When the matches do not fit on one page, the hook builds `map.clusters` from location buckets whose counts add up to `map.total`; render them as they come and never fetch or merge more pages. Draw a bucket like any other cluster."
|
|
521
|
+
: "";
|
|
522
|
+
const clusterClick = studioMapClusterClickInstruction(hasBuckets);
|
|
523
|
+
return `Map search on \`/imoveis\` (list and map of the same query). The list stays: keep \`usePublicSearch\` for the list, including its sort and pagination. The visitor switches on the same page. \`?modo=mapa\` is the map — read it on first paint. The list is the URL without \`modo\`; do not write \`modo=lista\` or \`modo=grade\`. Choosing the map sets \`modo=mapa\` and drops \`page\`. Choosing the list removes \`modo\`. On the map, hide sort and pagination. Do not add a map pager. The heading stays. Filters apply to both. Load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` — never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`, never \`maps.googleapis.com\`, never \`@vis.gl/react-google-maps\`. From \`${STUDIO_SDK_PACKAGE}/react\` import useMapSearch; it fetches, debounces, and clusters. \`const map = useMapSearch({ siteId, baseUrl: GARAGEM_API_BASE, bounds, zoom, q, sort, location, filters, publishableKey })\` with the same q, sort, location, filters, and publishableKey as the list. Pass the map's current zoom on every zoom change, including after a cluster click. Changing zoom recomputes \`map.clusters\` and does not refetch; a bounds change refetches. Do not send filter_by, vector_query, or nl_query from the browser. Request page 1 and pageSize at most 100. Do not walk totalPages. Pins are the masked coordinates the API returned — plot them as returned, never geocode the street. Render \`map.clusters\` with \`google.maps.Marker\` (no map id needed), in two styles that never look alike. A cluster (\`count > 1\`) is a filled circle in the brand color with a white border and the white count as its label. A listing (\`count === 1\` with \`cluster.pin\`) is a white rounded-rectangle chip with a brand-color border, labelled with the short price in the brand color ("R$ 850 mil", "R$ 1,2 mi"; "Consulte" when the price is null or 0): \`icon: { path: "M-34,-12 h68 a6,6 0 0 1 6,6 v12 a6,6 0 0 1 -6,6 h-68 a6,6 0 0 1 -6,-6 v-12 a6,6 0 0 1 6,-6 z", fillColor: "#ffffff", fillOpacity: 1, strokeColor: brand, strokeWeight: 1.5, scale: 1, labelOrigin: new google.maps.Point(0, 0) }\`. Never draw a listing as a dot or a circle, and never without its price. Clicking a listing selects it and shows its card. The card content is \`toListingCardModel(map.listings.find((listing) => listing.id === pin.id))\` and shows, in order: a large cover (\`coverSrc\`, aspect 4/3, full card width), title, \`priceLabel\`, \`locationLabel\`, then the facts that are present: \`bedrooms\` quartos, \`bathrooms\` banheiros, \`parkingSpaces\` vagas, \`areaM2\` m². Title and price alone are incomplete. On a wide screen the card opens next to its pin, never at the bottom of the map, where it falls below the viewport when the page is scrolled. Use one \`google.maps.InfoWindow\` and open it on the clicked marker: \`infoWindow.open({ map: googleMap, anchor: marker })\`. Its content is a div that React fills with \`createPortal\`. The InfoWindow pans the map so the card is in view. On a narrow screen the same card sits in a bottom sheet across the map width. Dismissing it leaves the pins. While \`map.loading\` the map is \`aria-busy\` with a visible progress indicator and the previous pins stay mounted. ${clusterClick} Layout, top to bottom: query, heading, toolbar, then the view. Lista and Mapa are icon buttons with the site tooltip and \`aria-label\` “Lista” / “Mapa”, not icon-plus-text. On desktop the toolbar is one row: featured filters on the left, and the list/map toggle immediately beside the sort select on the right. On a narrow screen the filters stay in one horizontal scroll that does not wrap, and the toggle plus the sort sit together on the row below that scroll. That row fits the viewport and never widens the page; sort may truncate. On the map the sort is hidden, so the toggle keeps that place beside where the sort was. In map mode the map fills the remaining viewport height, with a minimum of about 240px. Keep the hook's 400ms viewport debounce. A drawn polygon is not required. Do not add a separate /mapa route, a regions page, or a map on the listing page. Do not call Street View or travel time inside the map search.${buckets}`;
|
|
477
524
|
}
|
|
478
525
|
|
|
479
526
|
/** True when the pinned tarball ships the market-data helpers. */
|
|
@@ -580,6 +627,13 @@ export function studioCodegenContractViolations(text: string): string[] {
|
|
|
580
627
|
}
|
|
581
628
|
}
|
|
582
629
|
}
|
|
630
|
+
if (!isShareLinkOnPin()) {
|
|
631
|
+
for (const name of STUDIO_SDK_CONTRACT.shareExports) {
|
|
632
|
+
if (mentionsExportName(text, name) && !violations.includes(name)) {
|
|
633
|
+
violations.push(name);
|
|
634
|
+
}
|
|
635
|
+
}
|
|
636
|
+
}
|
|
583
637
|
const pin = STUDIO_SDK_CONTRACT.minNpmVersion;
|
|
584
638
|
if (!marketExportsAvailableAt(pin)) {
|
|
585
639
|
for (const name of STUDIO_SDK_CONTRACT.marketExports) {
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Types for the public Share Link API (`GET`/`POST /api/sites/share/{token}`).
|
|
3
|
+
*
|
|
4
|
+
* This mirrors `resolveShareToken()` in Foundation
|
|
5
|
+
* (`apps/foundation/os/domain/sites/public/share-token.ts`) — treat it as a
|
|
6
|
+
* public contract (additive changes only), but note it is **today's raw
|
|
7
|
+
* shape**, not the friendly `Listing`/`ListingDetail` contract `getListing`
|
|
8
|
+
* returns. Field-visibility masking (price/address/agent redaction per the
|
|
9
|
+
* tenant's sharing config) is already applied server-side before you see
|
|
10
|
+
* this payload — do not try to "fix" a hidden price or address.
|
|
11
|
+
*
|
|
12
|
+
* For `entityType === "listing"`, `listing` is the same shape `getListing`
|
|
13
|
+
* returns. Render that. `entity` stays the raw Foundation payload.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
import type { ListingDetail } from "./types";
|
|
17
|
+
|
|
18
|
+
/** Entity kinds a share token can point at. Only `"listing"` is typed in
|
|
19
|
+
* detail today; the rest pass through as raw records pending follow-up
|
|
20
|
+
* work. */
|
|
21
|
+
export type ShareEntityType =
|
|
22
|
+
| "listing"
|
|
23
|
+
| "shortlist"
|
|
24
|
+
| "seller_report"
|
|
25
|
+
| "visit_itinerary"
|
|
26
|
+
| "pricing_tool"
|
|
27
|
+
| "visit_survey"
|
|
28
|
+
| "form"
|
|
29
|
+
| (string & {});
|
|
30
|
+
|
|
31
|
+
/** Why `getShareLink` failed. Maps 1:1 to `resolveShareToken`'s reasons. */
|
|
32
|
+
export type ShareLinkErrorReason =
|
|
33
|
+
| "not_found"
|
|
34
|
+
| "inactive"
|
|
35
|
+
| "expired"
|
|
36
|
+
| "password_required"
|
|
37
|
+
| "password_invalid"
|
|
38
|
+
| (string & {});
|
|
39
|
+
|
|
40
|
+
/** Raw listing + property fields for a `listing`-type share token.
|
|
41
|
+
* Foundation-internal column names — distinct from the public `Listing`
|
|
42
|
+
* type's field names (e.g. `parkingSpots` here vs. `parkingSpaces` there).
|
|
43
|
+
* See the module doc: a normalized, `ListingDetail`-shaped field is
|
|
44
|
+
* planned as an additive follow-up. */
|
|
45
|
+
export interface ShareListingEntity {
|
|
46
|
+
listing: {
|
|
47
|
+
id: string;
|
|
48
|
+
title: string;
|
|
49
|
+
description: string | null;
|
|
50
|
+
price: number | null;
|
|
51
|
+
currency: string | null;
|
|
52
|
+
priceVisibility: string | null;
|
|
53
|
+
listingType: string | null;
|
|
54
|
+
listingCode: string | null;
|
|
55
|
+
stage: string | null;
|
|
56
|
+
status: string | null;
|
|
57
|
+
visibility: string | null;
|
|
58
|
+
createdAt: string | null;
|
|
59
|
+
publishedAt: string | null;
|
|
60
|
+
propertyId: string | null;
|
|
61
|
+
isPrimaryMarket: boolean | null;
|
|
62
|
+
typologyId: string | null;
|
|
63
|
+
};
|
|
64
|
+
property: Record<string, unknown> | null;
|
|
65
|
+
media: Array<{
|
|
66
|
+
id: string;
|
|
67
|
+
src: string;
|
|
68
|
+
alt?: string;
|
|
69
|
+
type: "image" | "video" | "tour";
|
|
70
|
+
category?: string;
|
|
71
|
+
order?: number;
|
|
72
|
+
isPrimary?: boolean;
|
|
73
|
+
entityType?: string;
|
|
74
|
+
}>;
|
|
75
|
+
[key: string]: unknown;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Share-token metadata echoed back on a successful resolve. */
|
|
79
|
+
export interface ShareLinkToken {
|
|
80
|
+
entityType: ShareEntityType;
|
|
81
|
+
entityId: string;
|
|
82
|
+
[key: string]: unknown;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Successful `getShareLink` result. */
|
|
86
|
+
export interface ShareLinkSuccess {
|
|
87
|
+
ok: true;
|
|
88
|
+
/** `entity` is typed for `entityType === "listing"`; narrow with a type
|
|
89
|
+
* guard (`result.token.entityType === "listing"`) before reading
|
|
90
|
+
* listing-specific fields on other entity types. */
|
|
91
|
+
token: ShareLinkToken;
|
|
92
|
+
entity: ShareListingEntity | Record<string, unknown>;
|
|
93
|
+
branding?: Record<string, unknown>;
|
|
94
|
+
agentInfo?: Record<string, unknown>;
|
|
95
|
+
tenantConfig?: Record<string, unknown>;
|
|
96
|
+
site?: Record<string, unknown>;
|
|
97
|
+
shareDisplayConfig?: Record<string, unknown>;
|
|
98
|
+
requestConfig?: Record<string, unknown>;
|
|
99
|
+
offerForm?: Record<string, unknown>;
|
|
100
|
+
tenantId: string;
|
|
101
|
+
/**
|
|
102
|
+
* Present for `entityType === "listing"` once Foundation attaches the
|
|
103
|
+
* public `getListing` shape. Render this with the same listing-detail
|
|
104
|
+
* module as `/imoveis`. Absent on older payloads and on other entity types.
|
|
105
|
+
*/
|
|
106
|
+
listing?: ListingDetail;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** Failed `getShareLink` result. Branch UI on `reason`, not just `status`.
|
|
110
|
+
* `listingCode` / `site` are present on some errors (e.g. `password_required`
|
|
111
|
+
* for a listing share) so a password gate can still show which listing it's
|
|
112
|
+
* for. */
|
|
113
|
+
export interface ShareLinkError {
|
|
114
|
+
ok: false;
|
|
115
|
+
status: number;
|
|
116
|
+
reason: ShareLinkErrorReason | null;
|
|
117
|
+
message: string;
|
|
118
|
+
listingCode?: string;
|
|
119
|
+
site?: Record<string, unknown>;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
export type ShareLinkResult = ShareLinkSuccess | ShareLinkError;
|