@realadvisor-sites/sdk 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RealAdvisor SA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,331 @@
-# Temporary Holding Version
+# @realadvisor/sites-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The data client of a RealAdvisor site. It reads what an agency publishes from
+its CRM (organisation, teams, agents, listings, new-build developments) and
+sends enquiries back to it.
+
+It is a thin client of the REST API's `/v3/public` resource. The API owns
+every data rule (what is public, how prices and addresses are shown, caching).
+The SDK adds four things: transport, types, one error code per failure, and a
+ready-made enquiry endpoint.
+
+- No dependencies, web standards only (`fetch`, `Request`, `Response`). It
+  runs unchanged in Astro, React Router, a Cloudflare Worker and Node 22.
+- Server-side only. The key must never reach the browser.
+- On npm as `@realadvisor-sites/sdk`, installed as `@realadvisor/sites-sdk`
+  (`"npm:@realadvisor-sites/sdk@^0.4.0"`), or by path (`file:../sdk`).
+- The kit core (`kit-core`) and both kits (`kit-astro`, `kit-react`) take it
+  as a peer; a site depends on it next to its kit, same version.
+
+## Quick start
+
+Set two environment variables. The CRM sets both when it publishes a site.
+
+```sh
+SITES_API_URL=https://rest.realadvisor.com   # the REST API origin
+SITES_API_KEY=...                            # the site's own key (a secret)
+```
+
+Create one client and read:
+
+```ts
+import { createClient } from '@realadvisor/sites-sdk';
+
+const ra = createClient({
+  // The site's portals by name, `main` required. Without portals: the site's own.
+  portals: { main: '939666fc-c8d9-49e9-8e4b-19a6e9177e21' },
+});
+
+const organisation = await ra.organisation();
+const { data, pagination } = await ra.listings({ offer_type: 'buy', limit: 12 });
+
+console.log(organisation.name, pagination.total);
+for (const listing of data) console.log(listing.title, listing.price);
+```
+
+The client reads the two variables on each call, not when it is created. A
+build with no data access only fails where it reads data.
+
+## Reading data
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `organisation()` | `Organisation` | The agency the site is for. |
+| `teams()` | `Team[]` | Every team (office). The site's own team is first and has `primary: true`. |
+| `agents({ team_id? })` | `Agent[]` | The whole organisation without `team_id`. |
+| `listings(query?)` | `Page<Listing>` | One page. See the filters below. |
+| `allListings(query?)` | `Listing[]` | Every page of `listings(query)`. |
+| `listing(slugOrId, { locale? })` | `Listing \| null` | Live on any of the site's portals. `null` when not found. |
+| `developments({ team_id?, locale? })` | `Development[]` | New-build developments, without their units. |
+| `development(slugOrId, { locale? })` | `DevelopmentWithUnits \| null` | One development with its units. `null` when not found. |
+| `turnstileSiteKey()` | `string \| null` | The enquiry form's Turnstile key, kept 5 minutes. `null`: no widget. |
+
+Not found is never an error: `listing()` and `development()` answer `null`.
+
+### Listing filters
+
+Every filter is optional.
+
+| Filter | Type | Meaning |
+| --- | --- | --- |
+| `portal` | `string` | A name from the client's `portals`. Default `main`. |
+| `team_id` | `string` | Listings of one team's brokers. |
+| `offer_type` | `'buy' \| 'rent'` | |
+| `property_type` | `string` | Exact type name or a prefix: `apartment` matches `apartment_penthouse`. |
+| `status` | `'available' \| 'sold'` | |
+| `city` | `string` | Case- and accent-insensitive: `geneve` finds Genève. |
+| `min_price`, `max_price` | `number` | |
+| `min_rooms` | `number` | |
+| `locale` | `string` | The page language. See Languages. |
+| `limit` | `number` | 1 to 200. Default 24 (the API's own default is 50). |
+| `offset` | `number` | Up to 10 000. |
+
+### Languages
+
+`listings`, `allListings`, `listing`, `developments` and `development` take a
+`locale` (`de`, `fr-CH`, ...). With it, a listing's `title`, `description` and
+`description_text` (a live unit's `description`) come in that language when
+the agency wrote them in the CRM (the listing's custom texts, as its brochure
+shows them), else the original. `text_locale` is set when every text came in
+that language: mark it as the element's `lang`. A development's own texts
+have one language in the CRM. Without `locale`, the original texts. Both kits
+pass the page locale on a site with more than one locale.
+
+### Pages
+
+`listings()` answers one page, exactly as the API sends it:
+
+```ts
+type Page<T> = {
+  data: T[];
+  pagination: {
+    limit: number;
+    offset: number;
+    total: number;
+    total_is_capped: boolean; // true when `total` stopped counting at its cap
+    has_more: boolean;
+  };
+};
+```
+
+`teams()`, `agents()`, `developments()` and `allListings()` read every page for
+you and answer a plain array. The API accepts no offset past 10 000, so the
+array ends after 10 200 rows.
+
+### Portals
+
+A portal is a publication channel in the CRM. A listing shows on a site when
+it is live on one of the site's portals.
+
+```ts
+const ra = createClient({
+  portals: { main: '<portal id>', luxury: '<another portal id>' },
+});
+
+await ra.listings();                     // listings of `main`
+await ra.listings({ portal: 'luxury' }); // listings of `luxury`
+await ra.listing(slug);                  // found on any of the two
+```
+
+Enquiries always go to `main`. A client without `portals` names none: rest-api
+then uses the site's own portal, for reads and enquiries.
+
+## What the data looks like
+
+The types are the `/v3/public` schemas of the REST API, field for field, in
+the API's snake_case (`offer_type`, `first_name`, `living_surface`). A type
+test in `rest-api` fails when the two differ, so the types cannot drift.
+
+Four rules hold for every answer:
+
+1. **A field with no value is absent.** Never `null`, never `''`. Test with
+   `if (listing.price)`, not against `null`.
+2. **Arrays are always arrays.** `listing.photos` and `listing.features` exist
+   even when empty.
+3. **Descriptions are sanitized HTML.** Only `p`, `br`, `ul`, `ol`, `li`,
+   `strong`, `em`, `h3`, `h4`, no attributes. `description_text` is the same
+   text without tags, for meta tags and cards.
+4. **Coordinates are never exact.** `lat` and `lng` are rounded as the CRM's
+   address display option asks (about 10 m, 100 m or 1 km).
+
+A hidden price is absent, and `price_on_request` is then `true`; so are the
+prices that go with it (`rent_extra`, the parking prices).
+
+### Listing and unit facts
+
+Both carry these, each absent when the CRM has none. Money is in the record's
+`currency`, surfaces in m².
+
+| Field | Meaning |
+| --- | --- |
+| `balcony_surface`, `terrace_surface`, `garden_surface` | Outdoor surfaces. |
+| `floor` | 0 = ground floor. `building_floors`: floors of the building. |
+| `orientation` | `['south', 'west']`: the directions it faces. |
+| `construction_year`, `renovation_year` | |
+| `energy_class` | `A` to `G`. `energy_certificate_version`: the certificate it is from, as typed in the CRM. |
+| `minergie` | `minergie`, `minergie_p`, `minergie_eco` or `minergie_p_eco`. |
+| `heating` | CRM key: `heat_pump`, `gas`, `district`, ... Show it translated. |
+| `has_cellar`, `furnished`, `pets_allowed` | `true` or `false`. |
+| `indoor_parkings`, `outdoor_parkings` | Numbers of parkings. |
+| `charges` | Monthly charges of the property. |
+| `rent_extra` | Rentals: monthly extra costs on top of `price`. |
+| `parking_price` or `indoor_parking_price` / `outdoor_parking_price` | All parkings together, or per parking. `parking_included: true` when they are in `price`. |
+| `available_from` | Move-in date, `YYYY-MM-DD`. |
+| `video_url`, `virtual_visit_url` | Links. A unit has them, like its photos, when it is a live listing. |
+
+A unit also has `reference` (its number in the development, `A1.2`) and
+`site_plan_points`: its outline on the development's `site_plan`, as SVG
+polygon points in the image's own pixels
+(`<svg viewBox="0 0 {width} {height}"><polygon points={site_plan_points} /></svg>`
+over the image). A development has `developer`, `architect` and
+`general_contractor`: `{ name, website?, logo? }`.
+
+`Unit.name` ("4,5 pièces · Rez-de-jardin") is written by the API in French for
+now, whatever the site's language.
+
+All types are exported from the package root and from
+`@realadvisor/sites-sdk/types`:
+`Organisation`, `Team`, `Agent`, `Listing`, `Unit`, `Development`,
+`DevelopmentWithUnits`, `PropertyFacts`, `Company`, `Photo`, `Address`,
+`Socials`, `OfferType`, `ListingStatus`, `UnitStatus`, `Page`, `Pagination`,
+`ListingsQuery`, `TextQuery`, `Portals`, `ClientOptions`, `SitesClient`,
+`Fixture`, `FixtureTranslations`, `ErrorCode`.
+
+## Enquiries
+
+`handleEnquiry` is the site's whole enquiry endpoint: a standard `Request` in,
+a `Response` out. Mount it on one route.
+
+```ts
+// Astro: src/pages/api/enquiry.ts
+import { handleEnquiry } from '@realadvisor/sites-sdk';
+import { ra } from '../../lib/ra';
+
+export const prerender = false;
+export const POST = ({ request }) => handleEnquiry(request, ra);
+```
+
+It accepts a JSON body or a posted form with these fields:
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `name`, `email`, `message` | yes | At most 100, 200 and 5000 characters. |
+| `phone` | no | At most 40 characters. |
+| `listing_id`, `agent_id`, `team_id` | no | What the enquiry is about. |
+| `development_id`, `lot_id` | no | `lot_id` needs `development_id`. |
+| `contact_reason` | no | `buy`, `sell`, `valuation` or `other`. |
+| `locale`, `page_url` | no | `page_url` defaults to the `Referer` header. |
+| `idempotency_key` | no | 8 to 100 letters, digits, `-` or `_`. The same key never creates a second enquiry. |
+| `cf-turnstile-response` | when verification is on | The Turnstile widget adds it to the form. |
+
+It answers:
+
+| Case | JSON request | Form posted without JavaScript |
+| --- | --- | --- |
+| Sent | `200 { id }` | `303` to `redirect` with `?enquiry=sent` |
+| Preview (`SITE_MODE=preview`) | `200 { preview: true }`, nothing is sent | `?enquiry=preview` |
+| Refused | the code's status, `{ code, fields? }` | `?enquiry=error` |
+
+`redirect` is a form field: a path of the same site (default `/`).
+
+The answer carries codes, never sentences: the site's form words them in its
+own language. The visitor's IP (`cf-connecting-ip`, else `x-forwarded-for`) is
+passed on so the API can limit enquiries per visitor.
+
+### Verification (Turnstile)
+
+The API decides whether an enquiry needs a Turnstile token. Ask it for the
+public key the form's widget renders:
+
+```
+GET /v3/public/enquiries/verification   ->   { "site_key": "0x4AAA..." }
+```
+
+`site_key` is `null` while verification is off: render no widget then.
+`turnstileSiteKey()` reads it and keeps it 5 minutes (30 s while there is
+none); a failed lookup answers `null`.
+
+## Errors
+
+Every failure is a `SitesApiError` with one `code`:
+
+| `code` | Status | Meaning |
+| --- | --- | --- |
+| `invalid` | 400 | A field is wrong. `err.fields` says which, e.g. `{ email: 'invalid' }`. |
+| `invalid_portal` | 400 | A portal is not an API portal of the organisation. |
+| `invalid_team` | 400 | `team_id` is not a team of the organisation. |
+| `rejected` | 400 | The CRM refused the enquiry. |
+| `site_key` | 401, 403 | The key was revoked or rotated, or may not read this. |
+| `verification_required` | 403 | No valid Turnstile token. |
+| `rate_limited` | 429 | Too many enquiries from this visitor. |
+| `unavailable` | any other, or none | The API failed or did not answer in 8 s, or no data access is configured. Also a 409: an enquiry with the same `idempotency_key` is still being created. |
+
+```ts
+import { SitesApiError } from '@realadvisor/sites-sdk';
+
+try {
+  await ra.listings({ team_id });
+} catch (err) {
+  if (err instanceof SitesApiError && err.code === 'invalid_team') {
+    // err.status is the HTTP status (0 when the API gave none), err.fields the wrong fields
+  }
+  throw err;
+}
+```
+
+A read that finds the API unavailable is tried once more before it fails. An
+enquiry is never retried.
+
+## Caching
+
+The API caches reads for 60 seconds per key. A change in the CRM shows on the
+site within a minute. Do not add a cache of your own on top. Enquiries and the
+verification route are never cached.
+
+## Fixtures
+
+`createFixtureClient(fixture)` is a `SitesClient` with no network, for
+`pnpm dev`, builds and tests: the same methods and the same filters as the
+API, over a `Fixture` (`organisation`, `teams`, `agents`, `listings`,
+`developments`, in the API's shape). `turnstileSiteKey()` answers
+`FIXTURE_TURNSTILE_SITE_KEY` (a stand-in widget that never loads Turnstile)
+unless the fixture sets `turnstile_site_key`. It sends no enquiry:
+`handleEnquiry` refuses it, so answer a fixture-mode form yourself.
+
+A fixture listing or unit may carry its texts in other languages:
+
+```json
+{ "title": "Villa du lac", "translations": { "de": { "title": "Villa am See", "description": "<p>Seesicht</p>" } } }
+```
+
+With `locale`, the fixture client serves them as the API serves the CRM's
+(`text_locale` included; a unit's description only when it has one), and it
+never passes `translations` on.
+
+## Tests
+
+`createClient` takes `url`, `key` and `fetch` for tests only:
+
+```ts
+const ra = createClient({
+  portals: { main: 'p1' },
+  url: 'https://api.test',
+  key: 'test',
+  fetch: async () => Response.json({ id: 'o1', name: 'Demo Agency' }),
+});
+```
+
+```sh
+cd sdk && pnpm test    # node --test, no network
+cd rest-api && pnpm check    # includes the test that SDK types equal the /v3/public schemas
+```
+
+`rest-api/scripts/sites-sdk-smoke.mjs` runs the SDK against a live API; CI
+runs it on every branch preview.
+
+## Reference
+
+- REST contract: `rest-api/src/routes/public-schemas.ts`, served as OpenAPI at
+  `/v3/openapi.json`.
+- Types: [`src/types.ts`](src/types.ts).
+- Client: [`src/index.ts`](src/index.ts).

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@realadvisor-sites/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "The data client of every RealAdvisor site: createClient, createFixtureClient, handleEnquiry, SitesApiError and the types. No dependencies, web standards only: it runs unchanged in Astro, React Router and plain Node.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/realadvisor/sites.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/realadvisor/sites/tree/main/sdk#readme",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "check": "pnpm test",
+    "test": "node --experimental-strip-types --no-warnings=ExperimentalWarning --test \"test/*.test.ts\""
+  },
+  "engines": {
+    "node": ">=22.18"
+  }
+}

package/src/index.ts

@@ -0,0 +1,399 @@
+/**
+ * @realadvisor/sites-sdk: how a RealAdvisor site reads its data. One URL and
+ * one key (SITES_API_URL, SITES_API_KEY in process.env) in every framework
+ * and environment; rest-api owns every data rule, the SDK adds transport,
+ * types, `err.code` and the enquiry endpoint. Web standards only.
+ */
+import type {
+  Agent,
+  Fixture,
+  FixtureTranslations,
+  ClientOptions,
+  Development,
+  DevelopmentWithUnits,
+  ErrorCode,
+  Listing,
+  ListingsQuery,
+  Organisation,
+  Page,
+  SitesClient,
+  Team,
+  TextQuery,
+  Unit,
+} from './types.ts';
+
+export type * from './types.ts';
+
+const TIMEOUT_MS = 8000;
+const PAGE = 200;
+/** How long turnstileSiteKey() keeps a key (30 s when there is none). */
+const TURNSTILE_TTL_MS = 5 * 60 * 1000;
+/** The last offset rest-api accepts (its MAX_OFFSET). */
+const MAX_OFFSET = 10_000;
+const NO_ACCESS = 'no data access: set SITES_API_URL and SITES_API_KEY';
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Status `handleEnquiry` answers for each code. */
+const STATUS: Record<ErrorCode, number> = {
+  invalid: 400,
+  invalid_portal: 400,
+  invalid_team: 400,
+  rejected: 400,
+  site_key: 401,
+  verification_required: 403,
+  rate_limited: 429,
+  unavailable: 502,
+};
+
+export class SitesApiError extends Error {
+  readonly code: ErrorCode;
+  /** The HTTP status the API answered, 0 when none (timeout, network, no data access). */
+  readonly status: number;
+  /** `invalid`: the wrong fields, e.g. `{ email: 'invalid' }`. */
+  readonly fields?: Record<string, string>;
+
+  constructor(code: ErrorCode, message: string, opts: { status?: number; fields?: Record<string, string> } = {}) {
+    super(message);
+    this.name = 'SitesApiError';
+    this.code = code;
+    this.status = opts.status ?? 0;
+    if (opts.fields) this.fields = opts.fields;
+  }
+}
+
+/** The one code of an API failure, from its status and the body's `error`. */
+const codeOf = (status: number, error: unknown): ErrorCode => {
+  if (status === 400) {
+    return error === 'invalid_portal' || error === 'invalid_team' || error === 'rejected' ? error : 'invalid';
+  }
+  if (status === 401) return 'site_key';
+  if (status === 403) {
+    // Any other 403 (a key that may not read this) is the key's.
+    return error === 'verification_required' ? 'verification_required' : 'site_key';
+  }
+  if (status === 429) return 'rate_limited';
+  return 'unavailable';
+};
+
+const env = (name: string): string | undefined => {
+  const proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;
+  return proc?.env?.[name]?.trim() || undefined;
+};
+
+/** Sends the enquiry `handleEnquiry` built: kept off the client's public methods. */
+const SEND = Symbol('sites-sdk.send');
+
+type Send = (body: Record<string, unknown>, clientIp?: string) => Promise<{ id: string }>;
+
+const query = (q: Record<string, unknown>) => {
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(q)) if (v != null && v !== '') params.set(k, String(v));
+  const s = params.toString();
+  return s ? `?${s}` : '';
+};
+
+export const createClient = (opts: ClientOptions = {}): SitesClient => {
+  const portals = opts.portals;
+  // Read per call: a Worker's process.env is set by then, and a build
+  // without data access only fails where it reads data.
+  const access = () => {
+    const url = opts.url ?? env('SITES_API_URL');
+    const key = opts.key ?? env('SITES_API_KEY');
+    if (!url || !key) throw new SitesApiError('unavailable', NO_ACCESS);
+    return { root: url.replace(/\/+$/, ''), key };
+  };
+
+  const once = async (method: string, path: string, body?: unknown, headers: Record<string, string> = {}) => {
+    const { root, key } = access();
+    const doFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(), TIMEOUT_MS);
+    let res: Response;
+    try {
+      res = await doFetch(`${root}${path}`, {
+        method,
+        headers: {
+          accept: 'application/json',
+          authorization: `Bearer ${key}`,
+          ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+          ...headers,
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: abort.signal,
+      });
+    } catch (err) {
+      const timedOut = abort.signal.aborted;
+      throw new SitesApiError('unavailable', `${method} ${path}: ${timedOut ? `no answer in ${TIMEOUT_MS / 1000} s` : (err as Error).message}`);
+    } finally {
+      clearTimeout(timer);
+    }
+    return res;
+  };
+
+  /** One API call: JSON, or null on 404 when `orNull`. A GET that finds the API unavailable is tried once more. */
+  const call = async <T>(method: 'GET' | 'POST', path: string, init: { body?: unknown; headers?: Record<string, string>; orNull?: boolean } = {}): Promise<T> => {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const res = await once(method, path, init.body, init.headers);
+        if (res.ok) return (await res.json()) as T;
+        if (res.status === 404 && init.orNull) return null as T;
+        const err = (await res.json().catch(() => ({}))) as { error?: unknown; fields?: Record<string, string>; detail?: string; title?: string };
+        const code = codeOf(res.status, err.error);
+        throw new SitesApiError(code, `${method} ${path}: ${res.status} ${err.detail ?? err.title ?? (typeof err.error === 'string' ? err.error : code)}`, {
+          status: res.status,
+          fields: err.fields,
+        });
+      } catch (err) {
+        const retry = method === 'GET' && attempt === 0 && err instanceof SitesApiError && err.code === 'unavailable' && err.message !== NO_ACCESS;
+        if (!retry) throw err;
+      }
+    }
+  };
+
+  /** A portal by name; without `portals`, none: rest-api uses the site's own. */
+  const portalId = (name?: string) => {
+    if (!portals && name === undefined) return undefined;
+    const id = portals?.[name ?? 'main'];
+    if (!id) throw new SitesApiError('invalid_portal', `portal "${name}" is not in the client's portals`, { status: 400 });
+    return id;
+  };
+
+  /** Every portal of the client: a listing or unit live on any of them shows. */
+  const allPortals = () => (portals ? [...new Set(Object.values(portals))].join(',') : undefined);
+
+  let turnstile: { at: number; key: Promise<string | null> } | undefined;
+  const turnstileSiteKey = () => {
+    if (!turnstile || Date.now() - turnstile.at > TURNSTILE_TTL_MS) {
+      const key = call<{ site_key?: unknown }>('GET', '/v3/public/enquiries/verification').then(
+        res => (typeof res?.site_key === 'string' && res.site_key ? res.site_key : null),
+        (err: unknown) => {
+          // A 403 (a key that may not read this): no widget; rest-api still decides on the enquiry.
+          if (!(err instanceof SitesApiError && err.code === 'site_key' && err.status === 403)) {
+            console.error(`[sites-sdk] turnstile site key lookup failed: ${(err as Error).message}`);
+          }
+          return null;
+        },
+      );
+      const entry = { at: Date.now(), key };
+      // No key: ask again after 30 s, not 5 min.
+      void key.then(k => {
+        if (!k) entry.at = Date.now() - TURNSTILE_TTL_MS + 30_000;
+      });
+      turnstile = entry;
+    }
+    return turnstile.key;
+  };
+
+  const listings = async ({ portal, limit, ...q }: ListingsQuery = {}) => {
+    const n = Math.min(Math.max(Math.trunc(limit ?? 24), 1), PAGE);
+    return call<Page<Listing>>('GET', `/v3/public/listings${query({ ...q, portal_ids: portalId(portal), limit: n })}`);
+  };
+
+  /**
+   * Every row of a list: the first page gives the total, the others are read
+   * at once. It ends with the last page rest-api serves (offset MAX_OFFSET).
+   */
+  const all = async <T>(page: (limit: number, offset: number) => Promise<Page<T>>) => {
+    const first = await page(PAGE, 0);
+    const offsets: number[] = [];
+    for (let offset = PAGE; offset < first.pagination.total && offset <= MAX_OFFSET; offset += PAGE) offsets.push(offset);
+    const rest = await Promise.all(offsets.map(offset => page(PAGE, offset)));
+    return [first, ...rest].flatMap(p => p.data);
+  };
+  const list = <T>(path: string, q: Record<string, unknown> = {}) =>
+    all((limit, offset) => call<Page<T>>('GET', `${path}${query({ ...q, limit, offset })}`));
+
+  const client: SitesClient & { [SEND]: Send } = {
+    organisation: () => call<Organisation>('GET', '/v3/public/organisation'),
+    teams: () => list<Team>('/v3/public/teams'),
+    agents: (q = {}) => list<Agent>('/v3/public/agents', q),
+    listings,
+    allListings: (q = {}) => all((limit, offset) => listings({ ...q, limit, offset })),
+    listing: async (slugOrId, q = {}) => {
+      const id = slugOrId.match(UUID_RE)?.[0].toLowerCase();
+      if (!id) return null;
+      return call<Listing | null>('GET', `/v3/public/listings/${id}${query({ portal_ids: allPortals(), locale: q.locale })}`, { orNull: true });
+    },
+    developments: (q = {}) => list<Development>('/v3/public/developments', { ...q, portal_ids: allPortals() }),
+    development: (slugOrId, q = {}) =>
+      call<DevelopmentWithUnits | null>(
+        'GET',
+        `/v3/public/developments/${encodeURIComponent(slugOrId)}${query({ portal_ids: allPortals(), locale: q.locale })}`,
+        { orNull: true },
+      ),
+    turnstileSiteKey,
+    [SEND]: (body, clientIp) =>
+      call<{ id: string }>('POST', '/v3/public/enquiries', {
+        body: { ...body, portal_id: portalId() },
+        headers: clientIp ? { 'x-ra-client-ip': clientIp } : {},
+      }),
+  };
+  return client;
+};
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const LIMITS: Record<string, number> = { name: 100, email: 200, phone: 40, message: 5000 };
+const REASONS = new Set(['buy', 'sell', 'valuation', 'other']);
+const PASSED = ['phone', 'listing_id', 'agent_id', 'development_id', 'lot_id', 'team_id', 'contact_reason', 'locale', 'page_url', 'idempotency_key'];
+
+const readBody = async (request: Request): Promise<Record<string, string>> => {
+  const out: Record<string, string> = {};
+  if ((request.headers.get('content-type') ?? '').includes('application/json')) {
+    const json = (await request.json().catch(() => null)) as Record<string, unknown> | null;
+    for (const [k, v] of Object.entries(json ?? {})) if (typeof v === 'string') out[k] = v;
+  } else {
+    const form = await request.formData().catch(() => null);
+    for (const [k, v] of form ?? []) if (typeof v === 'string') out[k] = v;
+  }
+  return out;
+};
+
+/**
+ * The site's whole enquiry endpoint: a standard Request in, a Response out.
+ * JSON in, JSON out: `{ id }`, `{ preview: true }` (SITE_MODE=preview: never
+ * sent) or `{ code, fields? }` with the code's status. Fields are named as
+ * rest-api names them (`listing_id`, `contact_reason`, ...). A form posted without
+ * JavaScript gets a 303 back to its `redirect` with `?enquiry=sent|preview|error`.
+ * Codes only: the site's form words them in its language.
+ */
+export const handleEnquiry = async (request: Request, ra: SitesClient): Promise<Response> => {
+  const body = await readBody(request);
+  const field = (k: string) => body[k]?.trim() || undefined;
+  const wantsJson =
+    (request.headers.get('accept') ?? '').includes('application/json') ||
+    (request.headers.get('content-type') ?? '').includes('application/json');
+  const respond = (status: number, json: Record<string, unknown>, state: 'sent' | 'preview' | 'error') => {
+    if (wantsJson) return Response.json(json, { status });
+    const back = field('redirect') ?? '/';
+    // Only a same-site path; the state goes before the #anchor.
+    const target = new URL(back.startsWith('/') && !back.startsWith('//') ? back : '/', 'http://site');
+    target.searchParams.set('enquiry', state);
+    return new Response(null, { status: 303, headers: { location: target.pathname + target.search + target.hash } });
+  };
+
+  const fields: Record<string, string> = {};
+  for (const k of ['name', 'email', 'message']) if (!field(k)) fields[k] = 'required';
+  if (field('email') && !EMAIL_RE.test(field('email')!)) fields.email = 'invalid';
+  for (const [k, max] of Object.entries(LIMITS)) if ((field(k)?.length ?? 0) > max) fields[k] = 'too_long';
+  if (field('contact_reason') && !REASONS.has(field('contact_reason')!)) fields.contact_reason = 'invalid';
+  if (field('lot_id') && !field('development_id')) fields.lot_id = 'invalid';
+  if (Object.keys(fields).length) return respond(400, { code: 'invalid', fields }, 'error');
+
+  if (env('SITE_MODE') === 'preview') return respond(200, { preview: true }, 'preview');
+
+  const input: Record<string, unknown> = { name: field('name'), email: field('email'), message: field('message') };
+  for (const k of PASSED) if (field(k)) input[k] = field(k);
+  input.page_url ??= request.headers.get('referer') ?? undefined;
+  const token = field('cf-turnstile-response') ?? field('turnstile_token');
+  if (token) input.turnstile_token = token;
+  const clientIp =
+    request.headers.get('cf-connecting-ip')?.trim() || request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || undefined;
+
+  const send = (ra as SitesClient & { [SEND]?: Send })[SEND];
+  if (!send) throw new TypeError('handleEnquiry needs a client from createClient');
+  try {
+    const { id } = await send(input, clientIp);
+    return respond(200, { id }, 'sent');
+  } catch (err) {
+    if (!(err instanceof SitesApiError)) throw err;
+    if (err.code === 'unavailable' || err.code === 'site_key') console.error(`[sites-sdk] enquiry: ${err.message}`);
+    return respond(STATUS[err.code], { code: err.code, ...(err.fields ? { fields: err.fields } : {}) }, 'error');
+  }
+};
+
+/** turnstileSiteKey() of a fixture: the form renders a stand-in widget and never loads Turnstile. */
+export const FIXTURE_TURNSTILE_SITE_KEY = 'fixture';
+
+/** The language of a locale (`de-CH` → `de`), as rest-api reads it. */
+const languageOf = (locale?: string): string | undefined => locale?.trim().toLowerCase().split(/[-_]/)[0] || undefined;
+
+const plainText = (html: string): string =>
+  html
+    .replace(/<\/(p|li|h3|h4)>|<br\s*\/?>/gi, '$& ')
+    .replace(/<[^>]*>/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+type Texts = { title?: string; description?: string; description_text?: string; text_locale?: string };
+
+/**
+ * A fixture record as the API serves it in `locale`: its `translations` in
+ * that language replace the title (listings) and the description (a unit's
+ * only when it has one: live units), `text_locale` set when every text
+ * served is translated. `translations` never leaves the client.
+ */
+const inLocale = <T extends Texts>(
+  { translations, ...rest }: T & FixtureTranslations,
+  locale: string | undefined,
+  kind: 'listing' | 'unit',
+): T => {
+  const record = rest as unknown as T;
+  const lang = languageOf(locale);
+  const t = lang ? translations?.[lang] : undefined;
+  if (!lang || !t) return record;
+  const out: T = { ...record };
+  const title = kind === 'listing' && !!t.title;
+  const description = !!t.description && (kind === 'listing' || record.description !== undefined);
+  if (title) out.title = t.title;
+  if (description) {
+    out.description = t.description;
+    out.description_text = t.description_text ?? plainText(t.description!);
+  }
+  const translated = (kind === 'unit' || title) && (description || out.description === undefined);
+  if (translated && (title || description)) out.text_locale = lang;
+  return out;
+};
+
+const fold = (s = ''): string => s.normalize('NFD').replace(/[̀-ͯ]/g, '').trim().toLowerCase();
+
+/**
+ * A SitesClient that answers from a fixture instead of rest-api: the same
+ * interface and the same filters as createClient, so a page written against
+ * it runs unchanged on live data. For `pnpm dev`, builds and tests without a
+ * key. It sends nothing: handleEnquiry refuses it.
+ */
+export const createFixtureClient = (fx: Fixture): SitesClient => {
+  const match = (l: Listing, q: ListingsQuery) =>
+    (!q.team_id || l.team_ids.includes(q.team_id)) &&
+    (!q.offer_type || l.offer_type === q.offer_type) &&
+    (!q.property_type || l.property_type === q.property_type || l.property_type.startsWith(`${q.property_type}_`)) &&
+    (!q.status || l.status === q.status) &&
+    (!q.city || fold(l.address.city) === fold(q.city)) &&
+    (q.min_price == null || (l.price != null && l.price >= q.min_price)) &&
+    (q.max_price == null || (l.price != null && l.price <= q.max_price)) &&
+    (q.min_rooms == null || (l.rooms != null && l.rooms >= q.min_rooms));
+  // Newest first, as rest-api lists them.
+  const found = (q: ListingsQuery) =>
+    [...fx.listings]
+      .sort((a, b) => b.published_at.localeCompare(a.published_at))
+      .filter(l => match(l, q))
+      .map(l => inLocale<Listing>(l, q.locale, 'listing'));
+  const listings = async (q: ListingsQuery = {}): Promise<Page<Listing>> => {
+    const all = found(q);
+    const limit = Math.min(Math.max(Math.trunc(q.limit ?? 24), 1), 200);
+    const offset = Math.max(Math.trunc(q.offset ?? 0), 0);
+    const data = all.slice(offset, offset + limit);
+    return { data, pagination: { limit, offset, total: all.length, total_is_capped: false, has_more: offset + data.length < all.length } };
+  };
+  const developments = (q: TextQuery = {}): DevelopmentWithUnits[] =>
+    (fx.developments ?? []).map(d => ({ ...d, units: d.units.map(u => inLocale<Unit>(u, q.locale, 'unit')) }));
+  const strip = ({ units: _units, ...d }: DevelopmentWithUnits): Development => d;
+  const byKey = <T extends { id: string; slug: string }>(arr: T[], s: string) => {
+    const id = s.match(UUID_RE)?.[0].toLowerCase();
+    return arr.find(x => x.slug === s || x.id === s || (!!id && x.id === id)) ?? null;
+  };
+  return {
+    organisation: async () => fx.organisation,
+    teams: async () => fx.teams,
+    agents: async (q = {}) => (q.team_id ? fx.agents.filter(a => a.team_ids.includes(q.team_id!)) : fx.agents),
+    listings,
+    allListings: async (q = {}) => found(q),
+    listing: async (s, q = {}) => {
+      const l = byKey(fx.listings, s);
+      return l && inLocale<Listing>(l, q.locale, 'listing');
+    },
+    developments: async (q = {}) => developments(q).filter(d => !q.team_id || d.team_ids.includes(q.team_id)).map(strip),
+    development: async (s, q = {}) => byKey(developments(q), s),
+    turnstileSiteKey: async () => (fx.turnstile_site_key === undefined ? FIXTURE_TURNSTILE_SITE_KEY : fx.turnstile_site_key),
+  };
+};

package/src/types.ts

@@ -0,0 +1,342 @@
+/**
+ * What @realadvisor/sites-sdk returns: the `/v3/public/*` contract of rest-api
+ * (src/routes/public-schemas.ts), field for field and in its snake_case. The
+ * SDK passes answers through; rest-api/test/public-sdk-types.test.ts fails
+ * when these types and the schemas differ. A field with no value is absent,
+ * arrays are arrays, descriptions are sanitized HTML, coordinates are never
+ * exact.
+ */
+
+export type Photo = { url: string; alt: string };
+
+export type Address = {
+  street?: string;
+  postcode?: string;
+  city?: string;
+  country?: string;
+  /** Rounded by the listing's address display option (about 10 m, 100 m or 1 km). */
+  lat?: number;
+  lng?: number;
+};
+
+export type Socials = {
+  facebook?: string;
+  instagram?: string;
+  linkedin?: string;
+  x?: string;
+  youtube?: string;
+  tiktok?: string;
+};
+
+/** The organisation the site is for (an agency with one or more teams). */
+export type Organisation = {
+  id: string;
+  name: string;
+  logo?: Photo;
+  website?: string;
+  address?: Address;
+  brand?: { primary: string };
+};
+
+/** One team (office, branch) of the organisation. */
+export type Team = {
+  id: string;
+  name: string;
+  /** The site's own team: first in `teams()`. */
+  primary?: boolean;
+  logo?: Photo;
+  website?: string;
+  phone?: string;
+  email?: string;
+  address: Address;
+  socials: Socials;
+  /** Sanitized HTML, same allowlist as Listing.description. */
+  description?: string;
+  description_text?: string;
+};
+
+export type Agent = {
+  id: string;
+  first_name: string;
+  last_name: string;
+  title?: string;
+  phone?: string;
+  email?: string;
+  photo?: Photo;
+  languages?: string[];
+  bio?: string;
+  /** The agent's active teams. */
+  team_ids: string[];
+};
+
+export type OfferType = 'buy' | 'rent';
+export type ListingStatus = 'available' | 'sold';
+
+/** The facts a listing and a unit share. Money is in the record's `currency`, surfaces in m². */
+export type PropertyFacts = {
+  /** Set when title and description came in the `locale` asked for; absent: the original texts. Mark it as the element's `lang`. */
+  text_locale?: string;
+  balcony_surface?: number;
+  terrace_surface?: number;
+  garden_surface?: number;
+  /** 0 = ground floor. */
+  floor?: number;
+  /** Floors of the building. */
+  building_floors?: number;
+  /** Directions the property faces. */
+  orientation?: Array<'north' | 'east' | 'south' | 'west'>;
+  construction_year?: number;
+  renovation_year?: number;
+  /** Energy consumption class of the certificate. */
+  energy_class?: 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G';
+  /** The certificate the class is from, as typed in the CRM. */
+  energy_certificate_version?: string;
+  /** Minergie label (Switzerland). */
+  minergie?: 'minergie' | 'minergie_p' | 'minergie_eco' | 'minergie_p_eco';
+  /** CRM heating key: `central`, `district`, `electric`, `gas`, `heat_pump`, `none`, `oil`, `other`, `pellet`, `solar`, `wood`. */
+  heating?: string;
+  has_cellar?: boolean;
+  indoor_parkings?: number;
+  outdoor_parkings?: number;
+  /** Monthly charges of the property. */
+  charges?: number;
+  /** Rentals: monthly extra costs on top of `price`. Absent when the price is hidden. */
+  rent_extra?: number;
+  /** Price of all the parkings together. Absent when the price is hidden. */
+  parking_price?: number;
+  /** Price per indoor parking. Absent when the price is hidden. */
+  indoor_parking_price?: number;
+  /** Price per outdoor parking. Absent when the price is hidden. */
+  outdoor_parking_price?: number;
+  /** true when the parkings are included in `price`. */
+  parking_included?: boolean;
+  /** Move-in date, `YYYY-MM-DD`. */
+  available_from?: string;
+  furnished?: boolean;
+  pets_allowed?: boolean;
+  video_url?: string;
+  virtual_visit_url?: string;
+};
+
+export type Listing = PropertyFacts & {
+  id: string;
+  /** `<title-slug>-<id>`: `listing()` takes it or the id. */
+  slug: string;
+  title: string;
+  /** Sanitized HTML: only p, br, ul, ol, li, strong, em, h3, h4, no attributes. Render with the kit's RichText. */
+  description?: string;
+  /** The description as plain text, for meta tags and cards. */
+  description_text?: string;
+  offer_type: OfferType;
+  /** CRM property type name, e.g. `apartment`, `house_villa`, `apartment_penthouse`. */
+  property_type: string;
+  status: ListingStatus;
+  /** Absent when hidden: `price_on_request` is then true. */
+  price?: number;
+  currency: string;
+  price_on_request?: boolean;
+  rooms?: number;
+  bedrooms?: number;
+  bathrooms?: number;
+  living_surface?: number;
+  land_surface?: number;
+  address: Address;
+  photos: Photo[];
+  agent?: Agent;
+  /** Feature keys (`elevator`, `balcony`, `parking`): show them translated, never raw. */
+  features: string[];
+  published_at: string;
+  /** The CRM reference agents and clients use (`58W5-DZRY`). */
+  reference?: string;
+  /** Teams of the listing's broker. */
+  team_ids: string[];
+};
+
+export type UnitStatus = 'available' | 'reserved' | 'sold';
+
+/** One unit (lot) of a new-build development. */
+export type Unit = PropertyFacts & {
+  id: string;
+  /** e.g. "4,5 pièces · Rez-de-jardin". */
+  name: string;
+  /** The unit number in the development (`A1.2`). */
+  reference?: string;
+  status: UnitStatus;
+  offer_type: OfferType;
+  property_type: string;
+  rooms?: number;
+  bedrooms?: number;
+  bathrooms?: number;
+  living_surface?: number;
+  floor_label?: string;
+  /** Only on units for sale whose price is public. */
+  price?: number;
+  currency: string;
+  price_on_request?: boolean;
+  /** Units that are live listings: same text and photos as the listing. */
+  description?: string;
+  description_text?: string;
+  photos?: Photo[];
+  /** The unit's outline on the development's `site_plan`: SVG polygon points in the image's own pixels. */
+  site_plan_points?: string;
+  /** Set when the unit is also a listing live on one of the client's portals: `listing(listing_slug)`. */
+  listing_slug?: string;
+  features: string[];
+};
+
+type Range = { min: number; max: number };
+
+/** A company of a development: its developer, architect or general contractor. */
+export type Company = { name: string; website?: string; logo?: Photo };
+
+export type Development = {
+  id: string;
+  slug: string;
+  title: string;
+  description?: string;
+  description_text?: string;
+  /** CRM development status: planning, construction, marketing, delivered, ... */
+  status?: string;
+  delivery_date?: string;
+  address: Address;
+  photos: Photo[];
+  site_plan?: Photo;
+  developer?: Company;
+  architect?: Company;
+  general_contractor?: Company;
+  stats: {
+    units: number;
+    available: number;
+    reserved: number;
+    sold: number;
+    price?: Range;
+    rooms?: Range;
+    living_surface?: Range;
+  };
+  currency: string;
+  agents: Agent[];
+  /** Teams of the development's broker. */
+  team_ids: string[];
+};
+
+export type DevelopmentWithUnits = Development & { units: Unit[] };
+
+/** The site's portals by name: `main` is the default and the enquiry portal. */
+export type Portals = { main: string } & Record<string, string>;
+
+export type ListingsQuery = {
+  /** A name from the client's `portals`. Default `main`. */
+  portal?: string;
+  team_id?: string;
+  offer_type?: OfferType;
+  /** Exact type name, or a prefix: `apartment` matches `apartment_furnished_flat`. */
+  property_type?: string;
+  status?: ListingStatus;
+  /** Case- and accent-insensitive: `geneve` finds Genève. */
+  city?: string;
+  min_price?: number;
+  max_price?: number;
+  min_rooms?: number;
+  /** The page language (`de`, `fr-CH`): texts in it when the CRM has them (`text_locale`), else the original. */
+  locale?: string;
+  /** 1..200, default 24. */
+  limit?: number;
+  offset?: number;
+};
+
+/** Which language to read texts in. */
+export type TextQuery = {
+  /** The page language (`de`, `fr-CH`): texts in it when the CRM has them (`text_locale`), else the original. */
+  locale?: string;
+};
+
+export type Pagination = {
+  limit: number;
+  offset: number;
+  total: number;
+  /** true when `total` stopped counting at its cap. */
+  total_is_capped: boolean;
+  has_more: boolean;
+};
+
+/** One page of a list, as rest-api answers it. */
+export type Page<T> = { data: T[]; pagination: Pagination };
+
+export type ClientOptions = {
+  /** Without: the site's own portal (the key's), for reads and enquiries. */
+  portals?: Portals;
+  /** Tests only: else process.env.SITES_API_URL. */
+  url?: string;
+  /** Tests only: else process.env.SITES_API_KEY. */
+  key?: string;
+  /** Tests only: else globalThis.fetch. */
+  fetch?: typeof fetch;
+};
+
+export type SitesClient = {
+  organisation(): Promise<Organisation>;
+  /** Primary team first. */
+  teams(): Promise<Team[]>;
+  /** The whole organisation without team_id. */
+  agents(q?: { team_id?: string }): Promise<Agent[]>;
+  listings(q?: ListingsQuery): Promise<Page<Listing>>;
+  /** Every page of `listings(q)`. */
+  allListings(q?: Omit<ListingsQuery, 'limit' | 'offset'>): Promise<Listing[]>;
+  /** Live on any of the site's portals; null when not found. */
+  listing(slugOrId: string, q?: TextQuery): Promise<Listing | null>;
+  developments(q?: { team_id?: string } & TextQuery): Promise<Development[]>;
+  /** The units' texts follow `locale`; the CRM keeps a development's own texts in one language. */
+  development(slugOrId: string, q?: TextQuery): Promise<DevelopmentWithUnits | null>;
+  /**
+   * The public Turnstile key the enquiry form renders, kept 5 min. null: no
+   * widget (verification off, or the lookup failed). Fixture:
+   * FIXTURE_TURNSTILE_SITE_KEY, a stand-in that never loads Turnstile.
+   */
+  turnstileSiteKey(): Promise<string | null>;
+};
+
+/** A fixture record's texts in other languages, by language (`de`, `fr`, ...). */
+export type FixtureTranslations = {
+  translations?: Record<string, { title?: string; description?: string; description_text?: string }>;
+};
+
+/**
+ * A site's data without the API (`createFixtureClient`): the same records,
+ * as the API answers them. Sites may add their own keys. A listing or unit
+ * may carry `translations`: with `locale`, the fixture client serves them as
+ * the API serves the CRM's (`text_locale` when every text is translated),
+ * and never passes `translations` on.
+ */
+export type Fixture = {
+  organisation: Organisation;
+  /** Primary team first. */
+  teams: Team[];
+  agents: Agent[];
+  listings: Array<Listing & FixtureTranslations>;
+  developments?: Array<Omit<DevelopmentWithUnits, 'units'> & { units: Array<Unit & FixtureTranslations> }>;
+  /** The portals a live client of this site uses. */
+  portals?: Portals;
+  /** What turnstileSiteKey() answers. Default FIXTURE_TURNSTILE_SITE_KEY; null: no widget. */
+  turnstile_site_key?: string | null;
+};
+
+/**
+ * Every failure, as `err.code`. Not found is never an error (`null`).
+ * - `invalid` 400: a field is wrong, `fields` says which.
+ * - `invalid_portal` 400: a portal is not an api portal of the organisation.
+ * - `invalid_team` 400: team_id is not a team of the organisation.
+ * - `rejected` 400: the CRM refused the enquiry.
+ * - `site_key` 401, 403: the site's key was revoked or rotated, or may not read this.
+ * - `verification_required` 403: no valid Turnstile token.
+ * - `rate_limited` 429: too many enquiries.
+ * - `unavailable` any other status, a timeout, or no data access configured.
+ */
+export type ErrorCode =
+  | 'invalid'
+  | 'invalid_portal'
+  | 'invalid_team'
+  | 'rejected'
+  | 'site_key'
+  | 'verification_required'
+  | 'rate_limited'
+  | 'unavailable';