@acms-subir/core 0.3.6 → 0.3.8

package/src/lib/maps/parse.ts

@@ -0,0 +1,180 @@
+// Pasted map links → a location, with no network. Handles Google Maps (long
+// links, ?q=/query=/ll=, embed iframes), Apple Maps, OpenStreetMap, plain
+// "lat, lng" text, and online-meeting links (Zoom, Meet, Teams…), which come
+// back as kind 'meeting' with no pin. Short links (maps.app.goo.gl) need a
+// server-side redirect walk first — see resolveMapLink in ./service.
+
+import type { ParsedLocation } from './types';
+
+const MEETING = /(^|\.)(zoom\.us|zoom\.com|meet\.google\.com|teams\.microsoft\.com|teams\.live\.com|webex\.com|whereby\.com|meet\.jit\.si|jit\.si)$/i;
+const GOOGLE = /(^|\.)google\.[a-z.]{2,6}$/i;
+const APPLE = /^maps\.apple(\.com)?$/i;
+const OSM = /(^|\.)openstreetmap\.org$/i;
+
+const num = (s: string | null | undefined): number | null => {
+  if (s === null || s === undefined || s.trim() === '') return null;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : null;
+};
+
+export const validLat = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n) && n >= -90 && n <= 90;
+export const validLng = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n) && n >= -180 && n <= 180;
+
+// "40.7484, -73.9857" → pin (both in range), else null
+export function parseLatLng(s: string | null | undefined): { lat: number; lng: number } | null {
+  const m = s?.trim().match(/^(-?\d{1,3}(?:\.\d+)?)\s*,\s*(-?\d{1,3}(?:\.\d+)?)$/);
+  if (!m) return null;
+  const lat = Number(m[1]);
+  const lng = Number(m[2]);
+  return validLat(lat) && validLng(lng) ? { lat, lng } : null;
+}
+
+const decode = (s: string) => {
+  try { return decodeURIComponent(s.replace(/\+/g, ' ')); } catch { return s.replace(/\+/g, ' '); }
+};
+const clean = (s: string) => s.replace(/\s+/g, ' ').trim();
+
+// "Empire State Building, 20 W 34th St., New York, NY 10001" → name + address.
+// A first part that starts with a number is a street, not a name: the whole
+// string is the address then.
+export function splitPlace(text: string): { name: string; address: string } {
+  const t = clean(text);
+  if (!t) return { name: '', address: '' };
+  const parts = t.split(',').map((p) => p.trim()).filter(Boolean);
+  if (parts.length < 2) return /^\d/.test(t) ? { name: '', address: t } : { name: t, address: '' };
+  if (/^\d/.test(parts[0])) return { name: '', address: parts.join(', ') };
+  return { name: parts[0], address: parts.slice(1).join(', ') };
+}
+
+function result(kind: ParsedLocation['kind'], fields: Partial<ParsedLocation>): ParsedLocation {
+  const lat = validLat(fields.lat) && validLng(fields.lng) ? fields.lat : null;
+  const lng = lat === null ? null : (fields.lng as number);
+  return { kind, name: fields.name ?? '', address: fields.address ?? '', lat, lng, url: fields.url ?? '' };
+}
+
+// a short Google Maps link that only a redirect can expand
+export function isShortMapLink(input: string): boolean {
+  let u: URL;
+  try { u = new URL(input.trim()); } catch { return false; }
+  const host = u.hostname.toLowerCase();
+  if (host === 'maps.app.goo.gl') return true;
+  return host === 'goo.gl' && u.pathname.startsWith('/maps');
+}
+
+// the src of a pasted <iframe …>, else the input itself
+function urlFrom(input: string): { url: string; embed: boolean } {
+  const s = input.trim();
+  if (/^<iframe[\s>]/i.test(s) || /<iframe[\s>]/i.test(s)) {
+    const m = s.match(/\ssrc\s*=\s*(["'])(.*?)\1/i) ?? s.match(/\ssrc\s*=\s*([^\s>]+)/i);
+    const src = m ? (m[2] ?? m[1]) : '';
+    return { url: src.replace(/&amp;/g, '&'), embed: true };
+  }
+  return { url: s, embed: false };
+}
+
+function parseGoogle(u: URL, embed: boolean, original: string): ParsedLocation | null {
+  const path = u.pathname;
+  const href = u.href;
+  const q = u.searchParams;
+  // embed iframes: /maps/embed?pb=!1m18…!2d<lng>!3d<lat>…!2s<name>…
+  const pb = q.get('pb');
+  if (pb !== null || path.startsWith('/maps/embed')) {
+    if (pb) {
+      const lng = num(pb.match(/!2d(-?\d+(?:\.\d+)?)/)?.[1]);
+      const lat = num(pb.match(/!3d(-?\d+(?:\.\d+)?)/)?.[1]);
+      // the place name is the first !2s value that isn't a 2-letter region code
+      let name = '';
+      for (const m of pb.matchAll(/!2s([^!]*)/g)) {
+        const v = clean(decode(m[1]));
+        if (v.length > 2 && !/^0x[0-9a-f]+:0x[0-9a-f]+$/i.test(v)) { name = v; break; }
+      }
+      const parts = splitPlace(name);
+      if (lat !== null || name) return result('map', { ...parts, lat, lng, url: '' });
+    }
+    // Maps Embed API: /maps/embed/v1/place?q=…
+    const query = q.get('q') ?? '';
+    const pin = parseLatLng(query) ?? parseLatLng(q.get('center'));
+    if (pin) return result('map', { ...pin, url: '' });
+    if (query) return result('map', { ...splitPlace(query), url: '' });
+    return null;
+  }
+  // the dropped pin of a place: …/data=!3m1!4b1!4m6!3m5!…!8m2!3d<lat>!4d<lng>
+  const dLat = num(href.match(/!3d(-?\d+(?:\.\d+)?)/)?.[1]);
+  const dLng = num(href.match(/!4d(-?\d+(?:\.\d+)?)/)?.[1]);
+  // the viewport centre: …/@<lat>,<lng>,17z
+  const at = path.match(/@(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?)/);
+  let lat = dLat ?? num(at?.[1]);
+  let lng = dLat !== null ? dLng : num(at?.[2]);
+  let text = '';
+  const seg = path.match(/\/maps\/(?:place|search)\/([^/@]+)/);
+  if (seg) text = decode(seg[1]);
+  const query = q.get('q') ?? q.get('query') ?? q.get('daddr') ?? q.get('destination') ?? '';
+  if (!text && query) {
+    const pin = parseLatLng(query);
+    if (pin) { lat = lat ?? pin.lat; lng = lng ?? pin.lng; } else text = query;
+  }
+  const ll = parseLatLng(q.get('ll')) ?? parseLatLng(q.get('sll'));
+  if (lat === null && ll) { lat = ll.lat; lng = ll.lng; }
+  // a pin typed as the place ("/maps/place/40.7,-73.9") is a pin, not a name
+  const textPin = parseLatLng(text);
+  if (textPin) { text = ''; if (lat === null) { lat = textPin.lat; lng = textPin.lng; } }
+  if (!validLat(lat) || !validLng(lng)) { lat = null; lng = null; }
+  if (lat === null && !text) return null;
+  return result('map', { ...splitPlace(text), lat, lng, url: embed ? '' : original });
+}
+
+function parseApple(u: URL, original: string): ParsedLocation | null {
+  const q = u.searchParams;
+  const pin = parseLatLng(q.get('coordinate')) ?? parseLatLng(q.get('ll')) ?? parseLatLng(q.get('sll')) ?? parseLatLng(q.get('q'));
+  const query = q.get('name') ?? q.get('q') ?? '';
+  const name = parseLatLng(query) ? '' : clean(query);
+  const address = clean(q.get('address') ?? q.get('daddr') ?? '');
+  if (!pin && !name && !address) return null;
+  const parts = !address && name ? splitPlace(name) : { name, address };
+  return result('map', { ...parts, ...(pin ?? {}), url: original });
+}
+
+function parseOsm(u: URL, original: string): ParsedLocation | null {
+  const q = u.searchParams;
+  let lat = num(q.get('mlat'));
+  let lng = num(q.get('mlon'));
+  if (lat === null || lng === null) {
+    const m = u.hash.match(/map=\d+(?:\.\d+)?\/(-?\d+(?:\.\d+)?)\/(-?\d+(?:\.\d+)?)/);
+    lat = num(m?.[1]);
+    lng = num(m?.[2]);
+  }
+  const query = clean(q.get('query') ?? '');
+  if (!validLat(lat) || !validLng(lng)) { lat = null; lng = null; }
+  if (lat === null && !query) return null;
+  return result('map', { ...splitPlace(query), lat, lng, url: original });
+}
+
+/**
+ * A pasted map link, map embed (<iframe> HTML) or "lat, lng" → location.
+ * null = not something we understand (or a short link — resolve it first).
+ */
+export function parseMapLink(input: string): ParsedLocation | null {
+  if (!input || input.length > 10_000) return null;
+  const pin = parseLatLng(input);
+  if (pin) return result('map', pin);
+  const { url, embed } = urlFrom(input);
+  let u: URL;
+  try { u = new URL(url); } catch { return null; }
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') return null;
+  const host = u.hostname.toLowerCase();
+  if (MEETING.test(host)) return result('meeting', { url: u.href });
+  if (isShortMapLink(u.href)) return null;
+  const original = embed ? '' : url.trim();
+  if (GOOGLE.test(host) && (u.pathname.startsWith('/maps') || host.startsWith('maps.'))) return parseGoogle(u, embed, original);
+  if (APPLE.test(host) || (host === 'apple.com' && u.pathname.startsWith('/maps'))) return parseApple(u, original);
+  if (OSM.test(host)) return parseOsm(u, original);
+  return null;
+}
+
+// a link that opens a map app (not a meeting, not some random page)
+export function isMapLink(url: string): boolean {
+  if (!url) return false;
+  if (isShortMapLink(url)) return true;
+  const p = parseMapLink(url);
+  return p !== null && p.kind === 'map';
+}

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;
+    },
+  };
+}