@volter/twin-googlemaps 0.1.0

package/dist/src/googlemaps-data.js

@@ -0,0 +1,370 @@
+import { createHash } from 'node:crypto';
+/**
+ * Deterministic, NON-real geodata. A Google Maps twin cannot reproduce Google's
+ * real geospatial index, live traffic, or imagery; instead it returns faithful
+ * response SHAPES with stable, deterministic values. A given query always maps
+ * to the same canned result so verifies and tests are repeatable offline.
+ */
+/** Stable FNV-ish hash → hex, used to derive deterministic ids/coords. */
+export function stableHash(input) {
+    const s = typeof input === 'string' ? input : JSON.stringify(input);
+    return createHash('sha256').update(s).digest('hex').slice(0, 16);
+}
+/** Normalize a free-text address for stable keying (lowercase, collapse ws). */
+export function normalizeAddress(address) {
+    return address.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+/** Deterministic lat/lng in a plausible range derived from a seed string. */
+export function deterministicLatLng(seed) {
+    const h = stableHash(seed);
+    const a = parseInt(h.slice(0, 8), 16);
+    const b = parseInt(h.slice(8, 16), 16);
+    // lat in [-85, 85], lng in [-180, 180], rounded to 7 decimals like Google.
+    const lat = Math.round((((a % 17000000) / 100000) - 85) * 1e7) / 1e7;
+    const lng = Math.round((((b % 36000000) / 100000) - 180) * 1e7) / 1e7;
+    return { lat, lng };
+}
+export function viewportAround(loc, delta = 0.01) {
+    return {
+        northeast: { lat: Math.round((loc.lat + delta) * 1e7) / 1e7, lng: Math.round((loc.lng + delta) * 1e7) / 1e7 },
+        southwest: { lat: Math.round((loc.lat - delta) * 1e7) / 1e7, lng: Math.round((loc.lng - delta) * 1e7) / 1e7 },
+    };
+}
+// Place ids use Google's `ChIJ`-prefixed opaque token shape. These are canned.
+const PLACES = [
+    {
+        place_id: 'ChIJE9on3F3HwoAR9AhGJW_fL-I',
+        name: 'Los Angeles',
+        formatted_address: 'Los Angeles, CA, USA',
+        location: { lat: 34.0522342, lng: -118.2436849 },
+        types: ['locality', 'political'],
+        components: [
+            { long_name: 'Los Angeles', short_name: 'Los Angeles', types: ['locality', 'political'] },
+            { long_name: 'Los Angeles County', short_name: 'Los Angeles County', types: ['administrative_area_level_2', 'political'] },
+            { long_name: 'California', short_name: 'CA', types: ['administrative_area_level_1', 'political'] },
+            { long_name: 'United States', short_name: 'US', types: ['country', 'political'] },
+        ],
+    },
+    {
+        place_id: 'ChIJOwg_06VPwokRYv534QaPC8g',
+        name: 'New York',
+        formatted_address: 'New York, NY, USA',
+        location: { lat: 40.7127753, lng: -74.0059728 },
+        types: ['locality', 'political'],
+        components: [
+            { long_name: 'New York', short_name: 'New York', types: ['locality', 'political'] },
+            { long_name: 'New York', short_name: 'NY', types: ['administrative_area_level_1', 'political'] },
+            { long_name: 'United States', short_name: 'US', types: ['country', 'political'] },
+        ],
+    },
+    {
+        place_id: 'ChIJj61dQgK6j4AR4GeTYWZsKWw',
+        name: 'Mountain View',
+        formatted_address: '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA',
+        location: { lat: 37.4220656, lng: -122.0840897 },
+        types: ['street_address'],
+        components: [
+            { long_name: '1600', short_name: '1600', types: ['street_number'] },
+            { long_name: 'Amphitheatre Parkway', short_name: 'Amphitheatre Pkwy', types: ['route'] },
+            { long_name: 'Mountain View', short_name: 'Mountain View', types: ['locality', 'political'] },
+            { long_name: 'California', short_name: 'CA', types: ['administrative_area_level_1', 'political'] },
+            { long_name: 'United States', short_name: 'US', types: ['country', 'political'] },
+            { long_name: '94043', short_name: '94043', types: ['postal_code'] },
+        ],
+    },
+    {
+        place_id: 'ChIJdd4hrwug2EcRmSrV3Vo6llI',
+        name: 'London',
+        formatted_address: 'London, UK',
+        location: { lat: 51.5072178, lng: -0.1275862 },
+        types: ['locality', 'political'],
+        components: [
+            { long_name: 'London', short_name: 'London', types: ['locality', 'political'] },
+            { long_name: 'United Kingdom', short_name: 'GB', types: ['country', 'political'] },
+        ],
+    },
+    {
+        place_id: 'ChIJ51cu8IcbXWARiRtXIothAS4',
+        name: 'Tokyo',
+        formatted_address: 'Tokyo, Japan',
+        location: { lat: 35.6761919, lng: 139.6503106 },
+        types: ['locality', 'political'],
+        components: [
+            { long_name: 'Tokyo', short_name: 'Tokyo', types: ['locality', 'political'] },
+            { long_name: 'Japan', short_name: 'JP', types: ['country', 'political'] },
+        ],
+    },
+];
+const ZERO_RESULTS_MARKERS = ['nowhere', 'zzzznoresult', 'zero_results', 'this-place-does-not-exist'];
+/** Returns true for a query the twin deliberately maps to ZERO_RESULTS. */
+export function isZeroResultsQuery(q) {
+    const n = normalizeAddress(q);
+    return ZERO_RESULTS_MARKERS.some((m) => n.includes(m));
+}
+/** Find a canned place by fuzzy name/address substring match. */
+export function findPlaceByText(query) {
+    const n = normalizeAddress(query);
+    for (const p of PLACES) {
+        if (n.includes(normalizeAddress(p.name)))
+            return p;
+        if (normalizeAddress(p.formatted_address).includes(n) && n.length >= 3)
+            return p;
+    }
+    return null;
+}
+export function findPlaceById(placeId) {
+    return PLACES.find((p) => p.place_id === placeId) ?? null;
+}
+/** The country short_name (ccTLD-ish) for a canned place, for component filtering. */
+export function countryOf(p) {
+    return p.components.find((c) => c.types.includes('country'))?.short_name?.toLowerCase();
+}
+/** The locality long_name for a canned place (used in plus-code compound codes). */
+export function localityOf(p) {
+    return p.components.find((c) => c.types.includes('locality'))?.long_name
+        ?? p.components.find((c) => c.types.includes('administrative_area_level_1'))?.long_name
+        ?? p.name;
+}
+/** Nearest canned place to a lat/lng (for reverse geocoding). */
+export function findPlaceByLatLng(loc) {
+    let best = PLACES[0];
+    let bestD = Number.POSITIVE_INFINITY;
+    for (const p of PLACES) {
+        const d = (p.location.lat - loc.lat) ** 2 + (p.location.lng - loc.lng) ** 2;
+        if (d < bestD) {
+            bestD = d;
+            best = p;
+        }
+    }
+    return best;
+}
+export function allPlaces() {
+    return PLACES;
+}
+/**
+ * Localized display names for canned places, keyed by language code. The Geocoding
+ * API returns localized `formatted_address` / component names per the `language`
+ * parameter; the twin models this faithfully for a small set of languages and
+ * falls back to the English name otherwise.
+ */
+const LOCALIZED_NAMES = {
+    'Tokyo, Japan': { ja: '日本、東京都', fr: 'Tokyo, Japon', es: 'Tokio, Japón', de: 'Tokio, Japan' },
+    'London, UK': { ja: 'イギリス ロンドン', fr: 'Londres, Royaume-Uni', es: 'Londres, Reino Unido', de: 'London, Vereinigtes Königreich' },
+    'Los Angeles, CA, USA': { ja: 'アメリカ合衆国 カリフォルニア州 ロサンゼルス', fr: 'Los Angeles, Californie, États-Unis', es: 'Los Ángeles, California, EE. UU.', de: 'Los Angeles, Kalifornien, USA' },
+    'New York, NY, USA': { ja: 'アメリカ合衆国 ニューヨーク州 ニューヨーク', fr: 'New York, État de New York, États-Unis', es: 'Nueva York, EE. UU.', de: 'New York, USA' },
+};
+/** Localize a formatted_address for a `language` code (no-op for English/unknown). */
+export function localizeFormattedAddress(formatted_address, language) {
+    if (!language)
+        return formatted_address;
+    const lang = language.toLowerCase().split('-')[0];
+    if (lang === 'en')
+        return formatted_address;
+    return LOCALIZED_NAMES[formatted_address]?.[lang] ?? formatted_address;
+}
+/** Build a faithful GeocodeResult from a canned place. */
+export function geocodeResultFromPlace(p, locationType = 'ROOFTOP') {
+    return {
+        address_components: p.components,
+        formatted_address: p.formatted_address,
+        geometry: {
+            location: p.location,
+            location_type: locationType,
+            viewport: viewportAround(p.location),
+        },
+        place_id: p.place_id,
+        types: p.types,
+    };
+}
+/**
+ * Synthesize a deterministic GeocodeResult for an arbitrary (non-canned but
+ * valid) address so the twin never falsely 404s a well-formed query. Coordinates
+ * are derived from the address hash; shape is faithful.
+ */
+export function synthGeocodeResult(address) {
+    const loc = deterministicLatLng(normalizeAddress(address));
+    const placeId = `ChIJ${stableHash(address)}twin`;
+    return {
+        address_components: [
+            { long_name: address, short_name: address, types: ['route'] },
+            { long_name: 'United States', short_name: 'US', types: ['country', 'political'] },
+        ],
+        formatted_address: address,
+        geometry: { location: loc, location_type: 'GEOMETRIC_CENTER', viewport: viewportAround(loc) },
+        place_id: placeId,
+        types: ['route'],
+    };
+}
+/** Great-circle distance (haversine) in meters between two points. */
+export function haversineMeters(a, b) {
+    const R = 6371000;
+    const toRad = (d) => (d * Math.PI) / 180;
+    const dLat = toRad(b.lat - a.lat);
+    const dLng = toRad(b.lng - a.lng);
+    const lat1 = toRad(a.lat);
+    const lat2 = toRad(b.lat);
+    const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2) ** 2;
+    return Math.round(2 * R * Math.asin(Math.sqrt(h)));
+}
+/** Human "5.0 mi" / "1.2 km" text for a distance in meters (imperial default). */
+export function distanceText(meters, metric = false) {
+    if (metric) {
+        const km = meters / 1000;
+        return km >= 1 ? `${km.toFixed(1)} km` : `${meters} m`;
+    }
+    const mi = meters / 1609.344;
+    return mi >= 0.1 ? `${mi.toFixed(1)} mi` : `${Math.round(meters * 3.28084)} ft`;
+}
+/** Human "15 mins" / "1 hour 5 mins" text for a duration in seconds. */
+export function durationText(seconds) {
+    const mins = Math.round(seconds / 60);
+    if (mins < 60)
+        return `${mins} min${mins === 1 ? '' : 's'}`;
+    const h = Math.floor(mins / 60);
+    const m = mins % 60;
+    return m === 0 ? `${h} hour${h === 1 ? '' : 's'}` : `${h} hour${h === 1 ? '' : 's'} ${m} min${m === 1 ? '' : 's'}`;
+}
+/** Deterministic driving duration (seconds) for a distance — ~40 km/h average. */
+export function deterministicDuration(meters) {
+    return Math.max(60, Math.round((meters / 1000 / 40) * 3600));
+}
+/**
+ * A tiny polyline encoder (Google's Encoded Polyline Algorithm Format), used to
+ * produce a faithful `overview_polyline.points` for Directions responses.
+ */
+export function encodePolyline(points) {
+    let last = [0, 0];
+    let out = '';
+    const enc = (cur, prev) => {
+        let v = Math.round(cur * 1e5) - Math.round(prev * 1e5);
+        v = v < 0 ? ~(v << 1) : v << 1;
+        let s = '';
+        while (v >= 0x20) {
+            s += String.fromCharCode((0x20 | (v & 0x1f)) + 63);
+            v >>= 5;
+        }
+        s += String.fromCharCode(v + 63);
+        return s;
+    };
+    for (const p of points) {
+        out += enc(p.lat, last[0]);
+        out += enc(p.lng, last[1]);
+        last = [p.lat, p.lng];
+    }
+    return out;
+}
+/** Deterministic elevation (meters) for a lat/lng. */
+export function deterministicElevation(loc) {
+    const h = parseInt(stableHash(`${loc.lat},${loc.lng}`).slice(0, 8), 16);
+    return Math.round(((h % 400000) / 100 - 100) * 1e2) / 1e2; // -100m .. 3900m
+}
+/**
+ * Deterministic IANA time zone id + offsets for a lat/lng. When a UTC `timestamp`
+ * (seconds) is supplied, northern-hemisphere DST is computed faithfully: zones
+ * that observe DST (US/UK) return a non-zero `dstOffset` for timestamps that fall
+ * between mid-March and early November; UTC/Japan never observe DST.
+ */
+export function deterministicTimeZone(loc, timestamp) {
+    const zones = [
+        { timeZoneId: 'America/Los_Angeles', stdName: 'Pacific Standard Time', dstName: 'Pacific Daylight Time', rawOffset: -28800, observesDst: true },
+        { timeZoneId: 'America/New_York', stdName: 'Eastern Standard Time', dstName: 'Eastern Daylight Time', rawOffset: -18000, observesDst: true },
+        { timeZoneId: 'Europe/London', stdName: 'Greenwich Mean Time', dstName: 'British Summer Time', rawOffset: 0, observesDst: true },
+        { timeZoneId: 'Asia/Tokyo', stdName: 'Japan Standard Time', dstName: 'Japan Standard Time', rawOffset: 32400, observesDst: false },
+    ];
+    const idx = parseInt(stableHash(`${loc.lat},${loc.lng}`).slice(0, 4), 16) % zones.length;
+    const z = zones[idx];
+    let dstOffset = 0;
+    if (z.observesDst && timestamp !== undefined && Number.isFinite(timestamp)) {
+        const month = new Date(timestamp * 1000).getUTCMonth(); // 0..11
+        // Northern-hemisphere DST window: roughly mid-March (2) .. October (9).
+        if (month >= 2 && month <= 9)
+            dstOffset = 3600;
+    }
+    return {
+        timeZoneId: z.timeZoneId,
+        timeZoneName: dstOffset > 0 ? z.dstName : z.stdName,
+        rawOffset: z.rawOffset,
+        dstOffset,
+    };
+}
+/**
+ * Open Location Code (Plus Code) encoder. Produces a faithful global_code (the
+ * 11th char is '+' after position 8) and a compound_code (global suffix + a
+ * locality reference). This is the real OLC algorithm over a deterministic grid.
+ */
+const OLC_ALPHABET = '23456789CFGHJMPQRVWX';
+export function encodePlusCode(loc, codeLength = 10) {
+    const lat = Math.min(Math.max(loc.lat, -90), 90) + 90;
+    const lng = ((loc.lng + 180) % 360 + 360) % 360;
+    let code = '';
+    // First 10 chars: 5 pairs, each a base-20 digit for lat then lng.
+    let latPrecision = 20;
+    let lngPrecision = 20;
+    for (let i = 0; i < 5; i++) {
+        const latDigit = Math.floor(lat / latPrecision) % 20;
+        const lngDigit = Math.floor(lng / lngPrecision) % 20;
+        code += OLC_ALPHABET[latDigit];
+        code += OLC_ALPHABET[lngDigit];
+        if (i === 3)
+            code += '+';
+        latPrecision /= 20;
+        lngPrecision /= 20;
+    }
+    return code.slice(0, codeLength + 1);
+}
+export function plusCodeFor(loc, localityName) {
+    const global_code = encodePlusCode(loc);
+    // compound_code drops the 4-char area prefix and appends a locality reference.
+    const compound_code = `${global_code.slice(4)} ${localityName}`;
+    return { global_code, compound_code };
+}
+/** Deterministic next_page_token <-> offset codec for Places pagination. */
+export function encodePageToken(query, offset) {
+    return Buffer.from(`${normalizeAddress(query)}::${offset}`).toString('base64url');
+}
+export function decodePageToken(token) {
+    try {
+        const [query, offsetStr] = Buffer.from(token, 'base64url').toString('utf8').split('::');
+        const offset = Number(offsetStr);
+        if (query === undefined || !Number.isFinite(offset))
+            return null;
+        return { query, offset };
+    }
+    catch {
+        return null;
+    }
+}
+/** A faithful opening_hours block (weekday_text + periods) for a place. */
+export function openingHoursFor(p) {
+    const days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+    const periods = days.map((_d, i) => ({
+        open: { day: i, time: '0900' },
+        close: { day: i, time: '1700' },
+    }));
+    return {
+        open_now: true,
+        periods,
+        weekday_text: days.map((d) => `${d}: 9:00 AM – 5:00 PM`),
+    };
+}
+/** A faithful, deterministic set of reviews for a place. */
+export function reviewsFor(p) {
+    return [
+        {
+            author_name: 'A. Traveler',
+            rating: 5,
+            relative_time_description: 'a month ago',
+            text: `Great experience at ${p.name}.`,
+            time: 1700000000,
+            language: 'en',
+        },
+        {
+            author_name: 'B. Local',
+            rating: 4,
+            relative_time_description: '2 months ago',
+            text: `Solid spot in ${p.name}.`,
+            time: 1697000000,
+            language: 'en',
+        },
+    ];
+}

package/dist/src/googlemaps-perform-harness.d.ts

@@ -0,0 +1,5 @@
+import { type GoogleMapsExecute } from './googlemaps-connector.js';
+export declare function performPending(execute: GoogleMapsExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<number>;

package/dist/src/googlemaps-perform-harness.js

@@ -0,0 +1,17 @@
+// A MINIATURE OF THE HEAD, for this pack's own claims and suites (protocol 2). Not on the serve path.
+import { confirmAction, deployableEntries, worldNow } from '@volter/world-core';
+import { pushGoogleMapsAction } from "./googlemaps-connector.js";
+export async function performPending(execute, opts = {}) {
+    let pushed = 0;
+    for (const entry of deployableEntries('googlemaps', opts.root)) {
+        if (!(await pushGoogleMapsAction(entry, execute)))
+            continue;
+        confirmAction({
+            service: 'googlemaps', actionId: entry.id, subject: entry.subject, fields: entry.fields ?? {},
+            occurredAt: opts.occurredAt ?? worldNow(), receipt: { status: 'deployed' },
+            ...(opts.root !== undefined ? { root: opts.root } : {}),
+        });
+        pushed += 1;
+    }
+    return pushed;
+}

package/dist/src/googlemaps-server.d.ts

@@ -0,0 +1,14 @@
+/** Options every Google Maps-twin HTTP surface needs, independent of who owns the socket. */
+export interface GoogleMapsTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+export declare function createGoogleMapsTwinFetch(options?: GoogleMapsTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createGoogleMapsTwinServer(options?: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/googlemaps-server.js

@@ -0,0 +1,25 @@
+// Google Maps twin HTTP server — serve the full Google Maps Platform twin handler over HTTP so
+// the real clients (pointed at this base URL) work unmodified.
+//
+// FETCH-FIRST (runtime contract R12b): the pack's whole HTTP surface is the plain fetch below,
+// built from the kernel's ONE adaptation (`createTwinFetchFromHandler` — manifest door, body
+// read, header map, worldNow() stamp, JSON reply). This file contributes only VALUES. The
+// server is one line of Bun.serve around that same closure, so the standalone (R1) and hosted
+// lanes execute identical serving bytes.
+import { serveHttp } from '@volter/world-core';
+import { handleGoogleMapsTwinRequest } from "./googlemaps-twin.js";
+import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+export function createGoogleMapsTwinFetch(options = {}) {
+    return createTwinFetchFromHandler(handleGoogleMapsTwinRequest, {
+        ...options,
+        manifest: statefulTwinManifest({ vendor: 'googlemaps', twinOf: 'the Google Maps Platform web services', stores: 'deterministic geocoding/places/roads answers derived from the request' }),
+    });
+}
+export async function createGoogleMapsTwinServer(options = {}) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createGoogleMapsTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/dist/src/googlemaps-twin.d.ts

@@ -0,0 +1,2 @@
+import type { GoogleMapsRequest, GoogleMapsResponse } from './googlemaps-types.js';
+export declare function handleGoogleMapsTwinRequest(req: GoogleMapsRequest): Promise<GoogleMapsResponse>;