feat(providers): normalize location parsing

src/providers/location.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+
+import { formatLocationText, toLocationContext } from "./location.js";
+
+describe("provider location helpers", () => {
+  it("formats pin locations with accuracy", () => {
+    const text = formatLocationText({
+      latitude: 48.858844,
+      longitude: 2.294351,
+      accuracy: 12,
+    });
+    expect(text).toBe("📍 48.858844, 2.294351 ±12m");
+  });
+
+  it("formats named places with address and caption", () => {
+    const text = formatLocationText({
+      latitude: 40.689247,
+      longitude: -74.044502,
+      name: "Statue of Liberty",
+      address: "Liberty Island, NY",
+      accuracy: 8,
+      caption: "Bring snacks",
+    });
+    expect(text).toBe(
+      "📍 Statue of Liberty — Liberty Island, NY (40.689247, -74.044502 ±8m)\nBring snacks",
+    );
+  });
+
+  it("formats live locations with live label", () => {
+    const text = formatLocationText({
+      latitude: 37.819929,
+      longitude: -122.478255,
+      accuracy: 20,
+      caption: "On the move",
+      isLive: true,
+      source: "live",
+    });
+    expect(text).toBe(
+      "🛰 Live location: 37.819929, -122.478255 ±20m\nOn the move",
+    );
+  });
+
+  it("builds ctx fields with normalized source", () => {
+    const ctx = toLocationContext({
+      latitude: 1,
+      longitude: 2,
+      name: "Cafe",
+      address: "Main St",
+    });
+    expect(ctx).toEqual({
+      LocationLat: 1,
+      LocationLon: 2,
+      LocationAccuracy: undefined,
+      LocationName: "Cafe",
+      LocationAddress: "Main St",
+      LocationSource: "place",
+      LocationIsLive: false,
+    });
+  });
+});

src/providers/location.ts

@@ -0,0 +1,78 @@
+export type LocationSource = "pin" | "place" | "live";
+
+export type NormalizedLocation = {
+  latitude: number;
+  longitude: number;
+  accuracy?: number;
+  name?: string;
+  address?: string;
+  isLive?: boolean;
+  source?: LocationSource;
+  caption?: string;
+};
+
+type ResolvedLocation = NormalizedLocation & {
+  source: LocationSource;
+  isLive: boolean;
+};
+
+function resolveLocation(location: NormalizedLocation): ResolvedLocation {
+  const source =
+    location.source ??
+    (location.isLive
+      ? "live"
+      : location.name || location.address
+        ? "place"
+        : "pin");
+  const isLive = Boolean(location.isLive ?? source === "live");
+  return { ...location, source, isLive };
+}
+
+function formatAccuracy(accuracy?: number): string {
+  if (!Number.isFinite(accuracy)) return "";
+  return ` ±${Math.round(accuracy ?? 0)}m`;
+}
+
+function formatCoords(latitude: number, longitude: number): string {
+  return `${latitude.toFixed(6)}, ${longitude.toFixed(6)}`;
+}
+
+export function formatLocationText(location: NormalizedLocation): string {
+  const resolved = resolveLocation(location);
+  const coords = formatCoords(resolved.latitude, resolved.longitude);
+  const accuracy = formatAccuracy(resolved.accuracy);
+  const caption = resolved.caption?.trim();
+  let header = "";
+
+  if (resolved.source === "live" || resolved.isLive) {
+    header = `🛰 Live location: ${coords}${accuracy}`;
+  } else if (resolved.name || resolved.address) {
+    const label = [resolved.name, resolved.address].filter(Boolean).join(" — ");
+    header = `📍 ${label} (${coords}${accuracy})`;
+  } else {
+    header = `📍 ${coords}${accuracy}`;
+  }
+
+  return caption ? `${header}\n${caption}` : header;
+}
+
+export function toLocationContext(location: NormalizedLocation): {
+  LocationLat: number;
+  LocationLon: number;
+  LocationAccuracy?: number;
+  LocationName?: string;
+  LocationAddress?: string;
+  LocationSource: LocationSource;
+  LocationIsLive: boolean;
+} {
+  const resolved = resolveLocation(location);
+  return {
+    LocationLat: resolved.latitude,
+    LocationLon: resolved.longitude,
+    LocationAccuracy: resolved.accuracy,
+    LocationName: resolved.name,
+    LocationAddress: resolved.address,
+    LocationSource: resolved.source,
+    LocationIsLive: resolved.isLive,
+  };
+}