@acms-subir/core 0.3.6 → 0.3.7

package/src/lib/maps/places.ts

@@ -0,0 +1,109 @@
+// Saved places: save (with map images), keep upcoming events in step, count
+// usage, and start new events at the default place.
+import type { ContentRepository } from '../repo/types';
+import { EventLocation, type CalEvent, type Place, type Settings } from '../schema';
+import { ApiError } from '../api';
+import { featuredOccurrence } from '../calendar/events';
+import { mergeEventDraft } from '../drafts';
+import { validLat, validLng } from './parse';
+import { ensureMapImages, type MapsContext } from './service';
+
+export interface PlaceInput {
+  id?: string;
+  name: string;
+  address: string;
+  url: string;
+  lat: number | null;
+  lng: number | null;
+  notes: string;
+  isDefault: boolean;
+}
+
+// An event counts as upcoming while any occurrence hasn't ended (a repeating
+// event with no end date always does). Past events keep their copy of a
+// place: changing HQ's address must not rewrite last year's history.
+export function isUpcoming(e: CalEvent, settings: Pick<Settings, 'timezone'>, now: number): boolean {
+  const o = featuredOccurrence(e, settings, now);
+  return Boolean(o && o.end > now);
+}
+
+/** upcoming events per place id (the staged version of each event counts) */
+export function placeUsage(events: CalEvent[], settings: Pick<Settings, 'timezone'>, now = Date.now()): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const e of events) {
+    const m = mergeEventDraft(e);
+    const id = m.location.placeId;
+    if (id && isUpcoming(m, settings, now)) counts.set(id, (counts.get(id) ?? 0) + 1);
+  }
+  return counts;
+}
+
+const placeFields = (p: Place) => ({ name: p.name, address: p.address, url: p.url, lat: p.lat, lng: p.lng, mapImage: p.mapImage, mapImageDark: p.mapImageDark });
+const differs = (loc: EventLocation, p: Place) => Object.entries(placeFields(p)).some(([k, v]) => loc[k as keyof EventLocation] !== v);
+
+/**
+ * Copy a saved place into every upcoming event that uses it. Returns how many
+ * events changed.
+ *
+ * Drafts: a published event's staged edits are a separate copy. Both copies
+ * that point at this place are refreshed — the live page shows the new
+ * address right away, and pressing Update later won't bring the old one
+ * back. A staged copy that switched to another place (or to typed text) is
+ * left alone. Live writes go through setEventLocation, which keeps the
+ * staged draft intact (a normal live update would discard it), and guests
+ * with an RSVP are told when the name or address actually changed.
+ */
+export async function syncPlaceToEvents(repo: ContentRepository, place: Place, now = Date.now()): Promise<number> {
+  const settings = await repo.getSettings();
+  let changed = 0;
+  for (const e of await repo.listEvents()) {
+    const liveHit = e.location.placeId === place.id && isUpcoming(e, settings, now) && differs(e.location, place);
+    const staged = e.draft && 'location' in e.draft ? mergeEventDraft(e) : null;
+    const draftHit = Boolean(staged && staged.location.placeId === place.id && isUpcoming(staged, settings, now) && differs(staged.location, place));
+    if (!liveHit && !draftHit) continue;
+    await repo.setEventLocation(e.id, {
+      ...(liveHit ? { live: EventLocation.parse({ ...e.location, ...placeFields(place) }) } : {}),
+      ...(draftHit && staged ? { draft: EventLocation.parse({ ...staged.location, ...placeFields(place) }) } : {}),
+      notify: liveHit && (e.location.name !== place.name || e.location.address !== place.address),
+    });
+    changed++;
+  }
+  return changed;
+}
+
+/** create or update a place (map images included), then refresh its upcoming events */
+export async function savePlace(repo: ContentRepository, input: PlaceInput, ctx: MapsContext = {}): Promise<{ place: Place; updatedEvents: number }> {
+  const existing = input.id ? await repo.getPlace(input.id) : null;
+  if (input.id && !existing) throw new ApiError(404, 'That place no longer exists.');
+  const name = input.name.trim().slice(0, 300);
+  if (!name) throw new ApiError(400, 'Give the place a name.');
+  const url = input.url.trim().slice(0, 1000);
+  if (url && !/^https?:\/\//i.test(url)) throw new ApiError(400, 'The map link must start with https://.');
+  const pinOk = validLat(input.lat) && validLng(input.lng);
+  if ((input.lat !== null || input.lng !== null) && !pinOk) throw new ApiError(400, 'That pin isn’t a valid latitude and longitude.');
+  const lat = pinOk ? input.lat : null;
+  const lng = pinOk ? input.lng : null;
+  const images = await ensureMapImages(repo, {
+    name, address: input.address.trim(), lat, lng, showMap: true, placeId: '',
+    mapImage: existing?.mapImage ?? '', mapImageDark: existing?.mapImageDark ?? '',
+  }, ctx);
+  const data = {
+    name, address: input.address.trim().slice(0, 500), url, lat, lng, notes: input.notes.slice(0, 2000), isDefault: input.isDefault,
+    mapImage: images.mapImage, mapImageDark: images.mapImageDark,
+  };
+  let place: Place;
+  if (existing) {
+    await repo.updatePlace(existing.id, data);
+    place = (await repo.getPlace(existing.id))!;
+  } else {
+    place = await repo.createPlace(data);
+  }
+  const updatedEvents = await syncPlaceToEvents(repo, place);
+  return { place, updatedEvents };
+}
+
+/** the default place as an event location (null = none set) */
+export async function defaultPlaceLocation(repo: ContentRepository): Promise<EventLocation | null> {
+  const p = (await repo.listPlaces()).find((x) => x.isDefault);
+  return p ? EventLocation.parse({ ...placeFields(p), placeId: p.id, showMap: true }) : null;
+}

package/src/lib/maps/providers/geoapify.ts

@@ -0,0 +1,36 @@
+// Geoapify (OpenStreetMap data): autocomplete, reverse geocoding and static
+// maps with one API key. https://apidocs.geoapify.com
+import type { GeoResult } from '../types';
+import { arr, geo, getImage, getJson, obj, qs, s, usable, type MapsProvider, type ProviderEnv } from './http';
+
+export function geoapifyResults(json: unknown): GeoResult[] {
+  return arr(obj(json).results).map((raw) => {
+    const r = obj(raw);
+    const name = s(r.name);
+    return geo(name, name ? s(r.address_line2) || s(r.formatted) : s(r.formatted), r.lat, r.lon);
+  });
+}
+
+export function geoapify(env: ProviderEnv): MapsProvider {
+  const base = 'https://api.geoapify.com/v1/geocode';
+  return {
+    id: 'geoapify',
+    label: 'Geoapify',
+    attribution: 'Powered by Geoapify · © OpenMapTiles · © OpenStreetMap contributors',
+    async search(q, opts = {}) {
+      const json = await getJson(`${base}/autocomplete?${qs({ text: q, format: 'json', limit: opts.limit ?? 5, bias: opts.near ? `proximity:${opts.near.lng},${opts.near.lat}` : undefined, apiKey: env.key })}`, env);
+      return usable(geoapifyResults(json), opts.limit ?? 5);
+    },
+    async reverse(lat, lng) {
+      const json = await getJson(`${base}/reverse?${qs({ lat, lon: lng, format: 'json', limit: 1, apiKey: env.key })}`, env);
+      return geoapifyResults(json)[0] ?? null;
+    },
+    async staticMap(lat, lng, { width, height, dark }) {
+      const params = qs({
+        style: dark ? 'dark-matter' : 'osm-bright', width: Math.round(width / 2), height: Math.round(height / 2), scaleFactor: 2,
+        center: `lonlat:${lng},${lat}`, zoom: 15, marker: `lonlat:${lng},${lat};color:#e03131;size:large`, apiKey: env.key,
+      });
+      return getImage(`https://maps.geoapify.com/v1/staticmap?${params}`, env);
+    },
+  };
+}

package/src/lib/maps/providers/google.ts

@@ -0,0 +1,54 @@
+// Google Maps Platform: Places API (New) Text Search for suggestions (it
+// returns the pin in the same call, unlike Autocomplete + Details), the
+// Geocoding API for reverse lookups, and the Maps Static API.
+import type { GeoResult } from '../types';
+import { arr, geo, getImage, getJson, obj, qs, s, usable, type MapsProvider, type ProviderEnv } from './http';
+
+export function googlePlacesResults(json: unknown): GeoResult[] {
+  return arr(obj(json).places).map((raw) => {
+    const p = obj(raw);
+    const loc = obj(p.location);
+    return geo(s(obj(p.displayName).text), s(p.formattedAddress), loc.latitude, loc.longitude, s(p.googleMapsUri));
+  });
+}
+
+export function googleGeocodeResults(json: unknown): GeoResult[] {
+  return arr(obj(json).results).map((raw) => {
+    const r = obj(raw);
+    const loc = obj(obj(r.geometry).location);
+    return geo('', s(r.formatted_address), loc.lat, loc.lng);
+  });
+}
+
+// a muted night palette for the dark image (the Static API has no dark style)
+const DARK = [
+  'element:geometry|color:0x242f3e', 'element:labels.text.stroke|color:0x242f3e', 'element:labels.text.fill|color:0x8a8f98',
+  'feature:road|element:geometry|color:0x38414e', 'feature:road|element:geometry.stroke|color:0x212a37',
+  'feature:water|element:geometry|color:0x17263c', 'feature:poi|element:geometry|color:0x2b3544',
+];
+
+export function google(env: ProviderEnv): MapsProvider {
+  return {
+    id: 'google',
+    label: 'Google Maps',
+    attribution: 'Map data © Google',
+    async search(q, opts = {}) {
+      const body: Record<string, unknown> = { textQuery: q, pageSize: opts.limit ?? 5 };
+      if (opts.near) body.locationBias = { circle: { center: { latitude: opts.near.lat, longitude: opts.near.lng }, radius: 50000 } };
+      const json = await getJson('https://places.googleapis.com/v1/places:searchText', env, {
+        method: 'POST', body: JSON.stringify(body),
+        headers: { 'Content-Type': 'application/json', 'X-Goog-Api-Key': env.key, 'X-Goog-FieldMask': 'places.displayName,places.formattedAddress,places.location,places.googleMapsUri' },
+      });
+      return usable(googlePlacesResults(json), opts.limit ?? 5);
+    },
+    async reverse(lat, lng) {
+      const json = await getJson(`https://maps.googleapis.com/maps/api/geocode/json?${qs({ latlng: `${lat},${lng}`, key: env.key })}`, env);
+      return googleGeocodeResults(json)[0] ?? null;
+    },
+    async staticMap(lat, lng, { width, height, dark }) {
+      const params = qs({ center: `${lat},${lng}`, zoom: 15, size: `${Math.round(width / 2)}x${Math.round(height / 2)}`, scale: 2, markers: `color:red|${lat},${lng}`, key: env.key });
+      const style = dark ? DARK.map((d) => `&style=${encodeURIComponent(d)}`).join('') : '';
+      return getImage(`https://maps.googleapis.com/maps/api/staticmap?${params}${style}`, env);
+    },
+  };
+}

package/src/lib/maps/providers/http.ts

@@ -0,0 +1,96 @@
+// Shared plumbing for the maps adapters: one timeout, one identifying
+// User-Agent, and response mapping that never throws on odd payloads.
+import type { GeoResult } from '../types';
+
+export interface ProviderEnv {
+  key: string;
+  // self-hosted base URL (photon / nominatim / pelias), no trailing slash
+  url: string;
+  // "acms (+https://example.org)"
+  userAgent: string;
+}
+
+export interface SearchOptions {
+  near?: { lat: number; lng: number };
+  limit?: number;
+}
+
+export interface StaticMapOptions {
+  width: number;
+  height: number;
+  dark: boolean;
+}
+
+export interface StaticImage {
+  body: ArrayBuffer;
+  contentType: string;
+}
+
+export interface MapsProvider {
+  id: string;
+  label: string;
+  // credit shown under static map images (and in the admin)
+  attribution: string;
+  search(q: string, opts?: SearchOptions): Promise<GeoResult[]>;
+  reverse(lat: number, lng: number): Promise<GeoResult | null>;
+  staticMap?(lat: number, lng: number, opts: StaticMapOptions): Promise<StaticImage | null>;
+}
+
+export const TIMEOUT_MS = 6000;
+// static map images are small PNG/JPEGs; anything bigger is not a map
+const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
+
+export async function getJson(url: string, env: ProviderEnv, init: { method?: string; headers?: Record<string, string>; body?: string } = {}): Promise<unknown> {
+  const res = await fetch(url, {
+    method: init.method ?? 'GET',
+    body: init.body,
+    headers: { 'User-Agent': env.userAgent, Accept: 'application/json', ...(init.headers ?? {}) },
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error(`maps provider answered ${res.status}`);
+  return res.json();
+}
+
+export async function getImage(url: string, env: ProviderEnv): Promise<StaticImage | null> {
+  const res = await fetch(url, { headers: { 'User-Agent': env.userAgent, Accept: 'image/*' }, signal: AbortSignal.timeout(TIMEOUT_MS) });
+  if (!res.ok) throw new Error(`static map answered ${res.status}`);
+  const contentType = (res.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+  if (!/^image\/(png|jpeg|webp)$/.test(contentType)) throw new Error(`static map returned ${contentType || 'no content type'}`);
+  const body = await res.arrayBuffer();
+  if (!body.byteLength || body.byteLength > MAX_IMAGE_BYTES) throw new Error('static map image is empty or too large');
+  return { body, contentType };
+}
+
+const str = (v: unknown) => (typeof v === 'string' ? v.trim() : typeof v === 'number' ? String(v) : '');
+export const s = str;
+
+export function coord(v: unknown): number | null {
+  const n = typeof v === 'string' ? Number(v) : v;
+  return typeof n === 'number' && Number.isFinite(n) ? n : null;
+}
+
+// a result row; drops the name when it only repeats the start of the address
+export function geo(name: string, address: string, lat: unknown, lng: unknown, url = ''): GeoResult {
+  const la = coord(lat);
+  const ln = coord(lng);
+  const ok = la !== null && ln !== null && la >= -90 && la <= 90 && ln >= -180 && ln <= 180;
+  let n = name.trim();
+  let a = address.trim();
+  if (n && a.startsWith(`${n},`)) a = a.slice(n.length + 1).trim();
+  if (n && n === a) a = '';
+  return { name: n, address: a, lat: ok ? la : null, lng: ok ? ln : null, url };
+}
+
+export const joinParts = (...parts: unknown[]) => parts.map(str).filter(Boolean).join(', ');
+
+export const arr = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
+export const obj = (v: unknown): Record<string, unknown> => (v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
+
+export const qs = (params: Record<string, string | number | undefined>) =>
+  Object.entries(params)
+    .filter(([, v]) => v !== undefined && v !== '')
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+    .join('&');
+
+// rows with neither a name nor an address are useless as suggestions
+export const usable = (rows: GeoResult[], limit: number) => rows.filter((r) => r.name || r.address).slice(0, limit);

package/src/lib/maps/providers/index.ts

@@ -0,0 +1,37 @@
+// The adapter registry. Each provider is a small module behind MapsProvider.
+import type { MapsProviderId } from '../types';
+import type { MapsProvider, ProviderEnv } from './http';
+import { geoapify } from './geoapify';
+import { google } from './google';
+import { mapbox } from './mapbox';
+import { locationiq } from './locationiq';
+import { pelias, stadia } from './pelias';
+import { nominatim, photon } from './osm';
+
+export type { MapsProvider, ProviderEnv } from './http';
+
+export const PROVIDERS: Record<MapsProviderId, { label: string; selfHosted: boolean; staticMaps: boolean; create: (env: ProviderEnv) => MapsProvider }> = {
+  geoapify: { label: 'Geoapify', selfHosted: false, staticMaps: true, create: geoapify },
+  google: { label: 'Google Maps', selfHosted: false, staticMaps: true, create: google },
+  mapbox: { label: 'Mapbox', selfHosted: false, staticMaps: true, create: mapbox },
+  locationiq: { label: 'LocationIQ', selfHosted: false, staticMaps: true, create: locationiq },
+  stadia: { label: 'Stadia Maps', selfHosted: false, staticMaps: true, create: stadia },
+  photon: { label: 'Photon (self-hosted)', selfHosted: true, staticMaps: false, create: photon },
+  nominatim: { label: 'Nominatim (self-hosted)', selfHosted: true, staticMaps: false, create: nominatim },
+  pelias: { label: 'Pelias (self-hosted)', selfHosted: true, staticMaps: false, create: pelias },
+};
+
+export const PROVIDER_IDS = Object.keys(PROVIDERS) as MapsProviderId[];
+
+// credits for images made by each provider (the id is stored in the image's
+// file name, so the credit survives a later provider switch)
+export const ATTRIBUTION: Record<MapsProviderId, string> = {
+  geoapify: 'Powered by Geoapify · © OpenMapTiles · © OpenStreetMap contributors',
+  google: 'Map data © Google',
+  mapbox: '© Mapbox · © OpenStreetMap contributors',
+  locationiq: '© LocationIQ · © OpenStreetMap contributors',
+  stadia: '© Stadia Maps · © OpenMapTiles · © OpenStreetMap contributors',
+  photon: '© OpenStreetMap contributors',
+  nominatim: '© OpenStreetMap contributors',
+  pelias: '© OpenStreetMap contributors',
+};

package/src/lib/maps/providers/locationiq.ts

@@ -0,0 +1,35 @@
+// LocationIQ (OpenStreetMap data): autocomplete, reverse and static maps.
+import type { GeoResult } from '../types';
+import { arr, geo, getImage, getJson, obj, qs, s, usable, type MapsProvider, type ProviderEnv } from './http';
+
+export function locationiqResults(json: unknown): GeoResult[] {
+  const rows = Array.isArray(json) ? json : [json];
+  return rows.map((raw) => {
+    const r = obj(raw);
+    const place = s(r.display_place);
+    return place ? geo(place, s(r.display_address), r.lat, r.lon) : geo('', s(r.display_name), r.lat, r.lon);
+  }).filter((r) => r.lat !== null || r.address || r.name);
+}
+
+export function locationiq(env: ProviderEnv): MapsProvider {
+  return {
+    id: 'locationiq',
+    label: 'LocationIQ',
+    attribution: '© LocationIQ · © OpenStreetMap contributors',
+    async search(q, opts = {}) {
+      const near = opts.near ? { viewbox: `${opts.near.lng - 0.5},${opts.near.lat - 0.5},${opts.near.lng + 0.5},${opts.near.lat + 0.5}` } : {};
+      const json = await getJson(`https://api.locationiq.com/v1/autocomplete?${qs({ key: env.key, q, limit: opts.limit ?? 5, dedupe: 1, ...near })}`, env);
+      return usable(locationiqResults(arr(json)), opts.limit ?? 5);
+    },
+    async reverse(lat, lng) {
+      const json = await getJson(`https://us1.locationiq.com/v1/reverse?${qs({ key: env.key, lat, lon: lng, format: 'json' })}`, env);
+      return locationiqResults(json)[0] ?? null;
+    },
+    // no dark style: the light image is used in dark mode too
+    async staticMap(lat, lng, { width, height, dark }) {
+      if (dark) return null;
+      const params = qs({ key: env.key, center: `${lat},${lng}`, zoom: 15, size: `${Math.round(width / 2)}x${Math.round(height / 2)}`, scale: 2, format: 'png', markers: `icon:large-red-cutout|${lat},${lng}` });
+      return getImage(`https://maps.locationiq.com/v3/staticmap?${params}`, env);
+    },
+  };
+}

package/src/lib/maps/providers/mapbox.ts

@@ -0,0 +1,38 @@
+// Mapbox: Geocoding v6 (forward with autocomplete, reverse) and the Static
+// Images API. MAPS_API_KEY is a public access token (pk.…).
+import type { GeoResult } from '../types';
+import { arr, geo, getImage, getJson, obj, qs, s, usable, type MapsProvider, type ProviderEnv } from './http';
+
+export function mapboxResults(json: unknown): GeoResult[] {
+  return arr(obj(json).features).map((raw) => {
+    const f = obj(raw);
+    const p = obj(f.properties);
+    const c = obj(p.coordinates);
+    const pt = arr(obj(f.geometry).coordinates);
+    const lat = c.latitude ?? pt[1];
+    const lng = c.longitude ?? pt[0];
+    return p.feature_type === 'address' ? geo('', s(p.full_address) || s(p.name), lat, lng) : geo(s(p.name), s(p.place_formatted) || s(p.full_address), lat, lng);
+  });
+}
+
+export function mapbox(env: ProviderEnv): MapsProvider {
+  const base = 'https://api.mapbox.com/search/geocode/v6';
+  return {
+    id: 'mapbox',
+    label: 'Mapbox',
+    attribution: '© Mapbox · © OpenStreetMap contributors',
+    async search(q, opts = {}) {
+      const json = await getJson(`${base}/forward?${qs({ q, autocomplete: 'true', limit: opts.limit ?? 5, proximity: opts.near ? `${opts.near.lng},${opts.near.lat}` : undefined, access_token: env.key })}`, env);
+      return usable(mapboxResults(json), opts.limit ?? 5);
+    },
+    async reverse(lat, lng) {
+      const json = await getJson(`${base}/reverse?${qs({ latitude: lat, longitude: lng, limit: 1, access_token: env.key })}`, env);
+      return mapboxResults(json)[0] ?? null;
+    },
+    async staticMap(lat, lng, { width, height, dark }) {
+      const style = dark ? 'dark-v11' : 'streets-v12';
+      const size = `${Math.round(width / 2)}x${Math.round(height / 2)}@2x`;
+      return getImage(`https://api.mapbox.com/styles/v1/mapbox/${style}/static/pin-l+e03131(${lng},${lat})/${lng},${lat},15,0/${size}?${qs({ access_token: env.key })}`, env);
+    },
+  };
+}

package/src/lib/maps/providers/osm.ts

@@ -0,0 +1,59 @@
+// Self-hosted OpenStreetMap geocoders at MAPS_URL: Photon (built for
+// search-as-you-type) and Nominatim. Search + reverse only — neither draws
+// map images. Never point these at the public nominatim.openstreetmap.org:
+// its usage policy forbids autocomplete and use by platforms.
+import type { GeoResult } from '../types';
+import { arr, geo, getJson, joinParts, obj, qs, s, usable, type MapsProvider, type ProviderEnv } from './http';
+
+export function photonResults(json: unknown): GeoResult[] {
+  return arr(obj(json).features).map((raw) => {
+    const f = obj(raw);
+    const p = obj(f.properties);
+    const c = arr(obj(f.geometry).coordinates);
+    const street = [s(p.housenumber), s(p.street)].filter(Boolean).join(' ');
+    const region = [s(p.state), s(p.postcode)].filter(Boolean).join(' ');
+    const address = joinParts(street, s(p.city) || s(p.district) || s(p.county), region, s(p.country));
+    const isHouse = p.type === 'house' || (!p.name && street);
+    return geo(isHouse ? '' : s(p.name), address, c[1], c[0]);
+  });
+}
+
+export function nominatimResults(json: unknown): GeoResult[] {
+  const rows = Array.isArray(json) ? json : [json];
+  return rows.map((raw) => {
+    const r = obj(raw);
+    return geo(s(r.name), s(r.display_name), r.lat, r.lon);
+  }).filter((r) => r.lat !== null || r.address);
+}
+
+export function photon(env: ProviderEnv): MapsProvider {
+  return {
+    id: 'photon',
+    label: 'Photon (self-hosted)',
+    attribution: '© OpenStreetMap contributors',
+    async search(q, opts = {}) {
+      const json = await getJson(`${env.url}/api?${qs({ q, limit: opts.limit ?? 5, lat: opts.near?.lat, lon: opts.near?.lng })}`, env);
+      return usable(photonResults(json), opts.limit ?? 5);
+    },
+    async reverse(lat, lng) {
+      const json = await getJson(`${env.url}/reverse?${qs({ lat, lon: lng, limit: 1 })}`, env);
+      return photonResults(json)[0] ?? null;
+    },
+  };
+}
+
+export function nominatim(env: ProviderEnv): MapsProvider {
+  return {
+    id: 'nominatim',
+    label: 'Nominatim (self-hosted)',
+    attribution: '© OpenStreetMap contributors',
+    async search(q, opts = {}) {
+      const json = await getJson(`${env.url}/search?${qs({ q, format: 'jsonv2', limit: opts.limit ?? 5 })}`, env);
+      return usable(nominatimResults(json), opts.limit ?? 5);
+    },
+    async reverse(lat, lng) {
+      const json = await getJson(`${env.url}/reverse?${qs({ lat, lon: lng, format: 'jsonv2' })}`, env);
+      return obj(json).error ? null : nominatimResults(json)[0] ?? null;
+    },
+  };
+}

package/src/lib/maps/providers/pelias.ts

@@ -0,0 +1,51 @@
+// Pelias-style geocoders: Stadia Maps (hosted, with static maps) and a
+// self-hosted Pelias at MAPS_URL (search + reverse only).
+import type { GeoResult } from '../types';
+import { arr, geo, getImage, getJson, obj, qs, s, usable, type MapsProvider, type ProviderEnv, type SearchOptions } from './http';
+
+export function peliasResults(json: unknown): GeoResult[] {
+  return arr(obj(json).features).map((raw) => {
+    const f = obj(raw);
+    const p = obj(f.properties);
+    const c = arr(obj(f.geometry).coordinates);
+    const label = s(p.label);
+    return p.layer === 'address' || p.layer === 'street' ? geo('', label || s(p.name), c[1], c[0]) : geo(s(p.name), label, c[1], c[0]);
+  });
+}
+
+function peliasCalls(base: string, env: ProviderEnv, auth: Record<string, string>) {
+  return {
+    async search(q: string, opts: SearchOptions = {}) {
+      const near = opts.near ? { 'focus.point.lat': opts.near.lat, 'focus.point.lon': opts.near.lng } : {};
+      const json = await getJson(`${base}/v1/autocomplete?${qs({ text: q, size: opts.limit ?? 5, ...near, ...auth })}`, env);
+      return usable(peliasResults(json), opts.limit ?? 5);
+    },
+    async reverse(lat: number, lng: number) {
+      const json = await getJson(`${base}/v1/reverse?${qs({ 'point.lat': lat, 'point.lon': lng, size: 1, ...auth })}`, env);
+      return peliasResults(json)[0] ?? null;
+    },
+  };
+}
+
+export function stadia(env: ProviderEnv): MapsProvider {
+  return {
+    id: 'stadia',
+    label: 'Stadia Maps',
+    attribution: '© Stadia Maps · © OpenMapTiles · © OpenStreetMap contributors',
+    ...peliasCalls('https://api.stadiamaps.com/geocoding', env, { api_key: env.key }),
+    async staticMap(lat, lng, { width, height, dark }) {
+      const style = dark ? 'alidade_smooth_dark' : 'alidade_smooth';
+      const params = qs({ center: `${lat},${lng}`, zoom: 15, size: `${Math.round(width / 2)}x${Math.round(height / 2)}@2x`, markers: `${lat},${lng}`, api_key: env.key });
+      return getImage(`https://tiles.stadiamaps.com/static/${style}?${params}`, env);
+    },
+  };
+}
+
+export function pelias(env: ProviderEnv): MapsProvider {
+  return {
+    id: 'pelias',
+    label: 'Pelias (self-hosted)',
+    attribution: '© OpenStreetMap contributors',
+    ...peliasCalls(env.url, env, env.key ? { api_key: env.key } : {}),
+  };
+}