@volter/twin-googlemaps 0.1.0

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

@@ -0,0 +1,8 @@
+export type GoogleMapsConformanceReport = {
+    ok: boolean;
+    checksRun: number;
+    failures: string[];
+};
+export declare function checkGoogleMapsConformance(options?: {
+    root?: string;
+}): Promise<GoogleMapsConformanceReport>;

package/dist/src/googlemaps-conformance.js

@@ -0,0 +1,18 @@
+import { handleGoogleMapsTwinRequest } from "./googlemaps-twin.js";
+export async function checkGoogleMapsConformance(options = {}) {
+    const failures = [];
+    let checksRun = 0;
+    const check = (name, ok) => { checksRun += 1; if (!ok)
+        failures.push(name); };
+    const geo = await handleGoogleMapsTwinRequest({ method: 'GET', path: '/maps/api/geocode/json?address=Los%20Angeles', root: options.root });
+    check('geocode returns OK with a location', geo.status === 200
+        && geo.body.status === 'OK'
+        && typeof geo.body.results?.[0]?.geometry?.location?.lat === 'number');
+    const dm = await handleGoogleMapsTwinRequest({ method: 'GET', path: '/maps/api/distancematrix/json?origins=34.05,-118.24&destinations=40.71,-74.0', root: options.root });
+    check('distancematrix returns OK rows', dm.status === 200
+        && dm.body.status === 'OK'
+        && dm.body.rows?.[0]?.elements?.[0]?.status === 'OK');
+    const bad = await handleGoogleMapsTwinRequest({ method: 'GET', path: '/maps/api/geocode/json', root: options.root });
+    check('missing address rejects with INVALID_REQUEST', bad.body.status === 'INVALID_REQUEST');
+    return { ok: failures.length === 0, checksRun, failures };
+}

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

@@ -0,0 +1,94 @@
+import type { PerformContext, PushOutcome, RemoteExecute, TwinAction } from '@volter/world-core';
+import { GoogleMapsBudget, type GoogleMapsBudgetOptions } from './googlemaps-budget.js';
+export type GoogleMapsExecute = (req: {
+    method: string;
+    path: string;
+    body?: unknown;
+}) => Promise<{
+    status: number;
+    data: unknown;
+}>;
+/** The real Google Maps Platform web-service host. The ONLY place this pack names it as a target. */
+export declare const GOOGLEMAPS_API_BASE = "https://maps.googleapis.com";
+/**
+ * THE CHOKE POINT — the one place this pack builds a `GoogleMapsExecute` that really reaches
+ * maps.googleapis.com, and therefore the one place the rate budget has to be enforced.
+ *
+ * Reads the API key from `GOOGLE_MAPS_API_KEY` (never a literal, never a credentials file) and sends
+ * it the way Google documents for each surface: as the `key=` query parameter on the legacy
+ * `/maps/api/...` web services, and as the `X-Goog-Api-Key` header otherwise (Places API New /
+ * Address Validation) — see `googlemaps-auth.ts`, which models the same two forms.
+ *
+ * EVERY request is guarded: the budget is charged BEFORE it goes out (`checkBudget`, which THROWS
+ * instead of returning once the ceiling or a persisted cooldown says stop) and the response is fed
+ * back (`recordCall`) so a `Retry-After` / 429 / rate-limit-exhaustion signal becomes a persisted
+ * cooldown that makes every later call fail fast WITHOUT touching Google. There is deliberately NO
+ * option to disable the guard.
+ *
+ * No vendor SDK is imported: real-transport `fetch` keeps `@googlemaps/google-maps-services-js` a
+ * dev-only dependency, which the architecture guardrail requires.
+ */
+export declare function liveGoogleMapsExecute(opts?: {
+    apiKey?: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executes. Omit and one is constructed. Cannot be null. */
+    budget?: GoogleMapsBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: GoogleMapsBudgetOptions;
+}): GoogleMapsExecute;
+/**
+ * Pull geocode results for a set of addresses through an injected client (the
+ * real Maps Geocoding API in prod, a fake in tests) and fold each OK result into
+ * local state as a `geocode` override. Idempotent on the normalized address.
+ */
+export declare function pullGoogleMapsGeocodes(execute: GoogleMapsExecute, addresses: string[], opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<number>;
+/**
+ * Pull place details for a set of place ids, folding each into local state as a
+ * `place` resource snapshot. Idempotent on the place id.
+ */
+export declare function pullGoogleMapsPlaces(execute: GoogleMapsExecute, placeIds: string[], opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<number>;
+/**
+ * D7 consumer-facing pull entry point: pull from the real Maps API (geocodes for the given
+ * addresses + details for the given place ids) and fold into the twin in ONE shadow-diffed
+ * one observed batch, returning the standard `{ observed, deltasAppended }` result. The inputs ride on the
+ * options object (this is an input-driven stateless twin). Idempotent — a re-pull of identical
+ * state appends nothing (deltasAppended drops to 0).
+ */
+export declare function syncGoogleMapsFromReal(execute: GoogleMapsExecute, opts?: {
+    addresses?: string[];
+    placeIds?: string[];
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** A pending `geocode.upsert` action is pushed as a twin-only seed POST. */
+export declare function googleMapsRequestForAction(action: TwinAction): {
+    method: string;
+    path: string;
+    body?: unknown;
+} | null;
+export declare function pushGoogleMapsAction(action: TwinAction, execute: GoogleMapsExecute): Promise<boolean>;
+/** The pack's executor over the kernel's. */
+export declare function googleMapsExecuteOver(execute: RemoteExecute): GoogleMapsExecute;
+/** The refresh adapter: re-read every address the tree already holds a geocode for. The Geocoding API has no
+ *  inventory to list — what a world knows to ask about IS the addresses it has seen. */
+export declare function syncGoogleMapsFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** The perform adapter. The Google Maps APIs this twin serves are READ-ONLY: they answer questions about
+ *  the world and accept no writes, so no entry ever crosses — each settles with that reason. */
+export declare function performGoogleMapsAction(_execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome>;

package/dist/src/googlemaps-connector.js

@@ -0,0 +1,243 @@
+// Google Maps CONNECTOR — pull/push against an INJECTED `GoogleMapsExecute`, so every test and
+// every capability verify runs offline against a deterministic fake.
+//
+// `liveGoogleMapsExecute` below is the pack's ONE construction site for a real, network-calling
+// execute — the choke point the rate budget sits inside. Before it existed there was nowhere for a
+// guard to live: the pack only ever received an execute, so a budget could only be something the
+// caller remembered to opt into, and "the caller remembered" is exactly the assumption that cost a
+// ~4.5-day Figma token lockout (2026-07-25). See `googlemaps-budget.ts` for the numbers and the
+// documented limits behind them.
+//
+// The injected contract is UNCHANGED: everything below still takes a plain `GoogleMapsExecute`.
+import { observeResources, projectResources } from '@volter/world-core';
+import { normalizeAddress, stableHash } from "./googlemaps-data.js";
+import { GoogleMapsBudget, GoogleMapsBudgetError, googleMapsCallWeight } from "./googlemaps-budget.js";
+const DEFAULT_OCCURRED_AT = '1970-01-01T00:00:00.000Z';
+/** The real Google Maps Platform web-service host. The ONLY place this pack names it as a target. */
+export const GOOGLEMAPS_API_BASE = 'https://maps.googleapis.com';
+/**
+ * THE CHOKE POINT — the one place this pack builds a `GoogleMapsExecute` that really reaches
+ * maps.googleapis.com, and therefore the one place the rate budget has to be enforced.
+ *
+ * Reads the API key from `GOOGLE_MAPS_API_KEY` (never a literal, never a credentials file) and sends
+ * it the way Google documents for each surface: as the `key=` query parameter on the legacy
+ * `/maps/api/...` web services, and as the `X-Goog-Api-Key` header otherwise (Places API New /
+ * Address Validation) — see `googlemaps-auth.ts`, which models the same two forms.
+ *
+ * EVERY request is guarded: the budget is charged BEFORE it goes out (`checkBudget`, which THROWS
+ * instead of returning once the ceiling or a persisted cooldown says stop) and the response is fed
+ * back (`recordCall`) so a `Retry-After` / 429 / rate-limit-exhaustion signal becomes a persisted
+ * cooldown that makes every later call fail fast WITHOUT touching Google. There is deliberately NO
+ * option to disable the guard.
+ *
+ * No vendor SDK is imported: real-transport `fetch` keeps `@googlemaps/google-maps-services-js` a
+ * dev-only dependency, which the architecture guardrail requires.
+ */
+export function liveGoogleMapsExecute(opts = {}) {
+    const apiKey = opts.apiKey ?? process.env.GOOGLE_MAPS_API_KEY ?? '';
+    if (!apiKey)
+        throw new Error('GOOGLE_MAPS_API_KEY is not set — the live Google Maps client needs an API key');
+    const baseUrl = opts.baseUrl ?? GOOGLEMAPS_API_BASE;
+    const doFetch = opts.fetchImpl ?? fetch;
+    // There is no value a caller can pass to end up with an unguarded execute. `null`/`undefined` (or
+    // omitting it) build the default budget; anything that is not a REAL `GoogleMapsBudget` is refused
+    // loudly rather than trusted — a duck-typed stand-in with a no-op `checkBudget` would otherwise be
+    // the one clean way around the guard.
+    if (opts.budget !== undefined && opts.budget !== null && !(opts.budget instanceof GoogleMapsBudget)) {
+        throw new Error('liveGoogleMapsExecute: `budget` must be a GoogleMapsBudget — refusing to build a live Google Maps client around an unverified rate guard');
+    }
+    // The default ledger is keyed by a hash of THIS key — Google's quotas are per project/key, so a
+    // cwd-scoped ledger would hand the same key a fresh allowance per checkout/worktree/CI leg.
+    const budget = opts.budget instanceof GoogleMapsBudget
+        ? opts.budget
+        : new GoogleMapsBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+    return async (req) => {
+        requireVendorPath(req.path);
+        const method = (req.method || 'GET').toUpperCase();
+        const weight = googleMapsCallWeight(method, req.path);
+        // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+        const reservation = budget.checkBudget(weight);
+        const legacy = req.path.startsWith('/maps/api/');
+        const url = new URL(req.path, baseUrl);
+        if (legacy)
+            url.searchParams.set('key', apiKey);
+        const res = await doFetch(url.toString(), {
+            method,
+            headers: {
+                Accept: 'application/json',
+                ...(legacy ? {} : { 'X-Goog-Api-Key': apiKey }),
+                ...(req.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+            },
+            ...(req.body === undefined ? {} : { body: JSON.stringify(req.body) }),
+        });
+        const headers = lowerCasedHeaders(res.headers);
+        const text = await res.text();
+        let data = null;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            data = { raw: text };
+        }
+        // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+        // Retry-After beyond the cap is not something to sleep off) — the cooldown is persisted first
+        // either way, so the refusal survives the throw.
+        // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+        // call that louder refusal wins; an answer Google Maps ACCEPTED is kept, so a write that landed is
+        // never recorded as failed and performed again on retry.
+        try {
+            budget.recordCall(weight, headers, { status: res.status, reservation });
+        }
+        catch (error) {
+            if (!(error instanceof GoogleMapsBudgetError) || !res.ok)
+                throw error;
+        }
+        return { status: res.status, data };
+    };
+}
+/**
+ * Refuse a `path` that is not a same-origin ABSOLUTE PATH.
+ *
+ * `new URL(path, base)` treats `https://evil.test/x` AND the protocol-relative `//evil.test/x` as
+ * absolute and silently retargets the host — and this factory attaches the credential
+ * unconditionally, so a caller-supplied absolute path would exfiltrate it to an arbitrary server.
+ * Figma's guarded client sidesteps this by concatenating rather than resolving; this execute takes an
+ * arbitrary `{ path }` from its caller, so it validates instead. (§9 finding, 2026-07-26.)
+ *
+ * `/twin/...` is refused for a different reason: those are the twin's OWN seed routes
+ * (`*RequestForAction` builds them), which the real vendor has never heard of. Sending one live is a
+ * guaranteed 404 that still burns budget and puts the live credential on the wire for nothing.
+ */
+function requireVendorPath(path) {
+    if (typeof path !== 'string' || !/^\/(?!\/)/.test(path)) {
+        throw new Error(`liveGoogleMapsExecute: path must be a same-origin absolute path beginning with a single "/" (got ${String(path)}) — refusing to let a caller-supplied absolute URL retarget the host with the credential attached`);
+    }
+    if (path === '/twin' || path.startsWith('/twin/')) {
+        throw new Error(`liveGoogleMapsExecute: refusing to send the twin-only path ${path} to real Google Maps — that route exists only in the local twin`);
+    }
+}
+/** Response headers as a plain lower-cased record — what the kernel's back-off reader expects. */
+function lowerCasedHeaders(h) {
+    const out = {};
+    h.forEach((v, k) => { out[k.toLowerCase()] = v; });
+    return out;
+}
+/** Fetch + map geocode results into SyncResource[] (no fold) — shared by pull + syncFromReal. */
+async function collectGoogleMapsGeocodes(execute, addresses) {
+    const resources = [];
+    for (const address of addresses) {
+        const res = await execute({ method: 'GET', path: `/maps/api/geocode/json?address=${encodeURIComponent(address)}` });
+        if (res.status < 200 || res.status >= 300)
+            continue;
+        const data = res.data;
+        if (data.status !== 'OK' || !data.results?.length)
+            continue;
+        const norm = normalizeAddress(address);
+        const id = `geocode_${stableHash(norm)}`;
+        resources.push({ type: 'geocode', id, fields: { id, normalized: norm, address, result: data.results[0], source: 'connector' } });
+    }
+    return resources;
+}
+/** Fetch + map place details into SyncResource[] (no fold) — shared by pull + syncFromReal. */
+async function collectGoogleMapsPlaces(execute, placeIds) {
+    const resources = [];
+    for (const placeId of placeIds) {
+        const res = await execute({ method: 'GET', path: `/maps/api/place/details/json?place_id=${encodeURIComponent(placeId)}` });
+        if (res.status < 200 || res.status >= 300)
+            continue;
+        const data = res.data;
+        if (data.status !== 'OK' || !data.result)
+            continue;
+        resources.push({ type: 'place', id: `place_${placeId}`, fields: { id: `place_${placeId}`, placeId, ...data.result, source: 'connector' } });
+    }
+    return resources;
+}
+/**
+ * Pull geocode results for a set of addresses through an injected client (the
+ * real Maps Geocoding API in prod, a fake in tests) and fold each OK result into
+ * local state as a `geocode` override. Idempotent on the normalized address.
+ */
+export async function pullGoogleMapsGeocodes(execute, addresses, opts = {}) {
+    const resources = await collectGoogleMapsGeocodes(execute, addresses);
+    fold(resources, opts);
+    return resources.length;
+}
+/**
+ * Pull place details for a set of place ids, folding each into local state as a
+ * `place` resource snapshot. Idempotent on the place id.
+ */
+export async function pullGoogleMapsPlaces(execute, placeIds, opts = {}) {
+    const resources = await collectGoogleMapsPlaces(execute, placeIds);
+    fold(resources, opts);
+    return resources.length;
+}
+/**
+ * D7 consumer-facing pull entry point: pull from the real Maps API (geocodes for the given
+ * addresses + details for the given place ids) and fold into the twin in ONE shadow-diffed
+ * one observed batch, returning the standard `{ observed, deltasAppended }` result. The inputs ride on the
+ * options object (this is an input-driven stateless twin). Idempotent — a re-pull of identical
+ * state appends nothing (deltasAppended drops to 0).
+ */
+export async function syncGoogleMapsFromReal(execute, opts = {}) {
+    const geocodes = await collectGoogleMapsGeocodes(execute, opts.addresses ?? []);
+    const places = await collectGoogleMapsPlaces(execute, opts.placeIds ?? []);
+    const resources = [...geocodes, ...places];
+    const result = fold(resources, opts);
+    return { observed: result.observed, deltasAppended: result.appended };
+}
+/** One fold onto the head: protocol 2's observe, one batch, one instant. */
+function fold(resources, opts) {
+    const at = opts.occurredAt ?? DEFAULT_OCCURRED_AT;
+    return observeResources('googlemaps', resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:googlemaps:${at}`,
+    });
+}
+/** A pending `geocode.upsert` action is pushed as a twin-only seed POST. */
+export function googleMapsRequestForAction(action) {
+    if (action.operation !== 'geocode.upsert')
+        return null;
+    const fields = action.fields;
+    return { method: 'POST', path: '/twin/geocode', body: { address: fields.address, result: fields.result } };
+}
+export async function pushGoogleMapsAction(action, execute) {
+    const req = googleMapsRequestForAction(action);
+    if (!req)
+        return false;
+    const result = await execute(req);
+    return result.status >= 200 && result.status < 300;
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** The pack's executor over the kernel's. */
+export function googleMapsExecuteOver(execute) {
+    return async ({ method, path, body }) => {
+        const res = await execute({ method, path, headers: { accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+        let data = {};
+        if (res.body) {
+            try {
+                data = JSON.parse(res.body);
+            }
+            catch {
+                data = { error_message: res.body };
+            }
+        }
+        return { status: res.status, data };
+    };
+}
+/** The refresh adapter: re-read every address the tree already holds a geocode for. The Geocoding API has no
+ *  inventory to list — what a world knows to ask about IS the addresses it has seen. */
+export async function syncGoogleMapsFromRemote(execute, opts = {}) {
+    const addresses = [];
+    for (const r of projectResources('googlemaps', opts.root)) {
+        if (r.type !== 'geocode')
+            continue;
+        const address = r.address;
+        if (typeof address === 'string' && address)
+            addresses.push(address);
+    }
+    return syncGoogleMapsFromReal(googleMapsExecuteOver(execute), { addresses, ...(opts.root !== undefined ? { root: opts.root } : {}), ...(opts.occurredAt !== undefined ? { occurredAt: opts.occurredAt } : {}) });
+}
+/** The perform adapter. The Google Maps APIs this twin serves are READ-ONLY: they answer questions about
+ *  the world and accept no writes, so no entry ever crosses — each settles with that reason. */
+export async function performGoogleMapsAction(_execute, action, _ctx) {
+    return { externalId: action.subject.id, data: { performed: false, reason: `${action.operation ?? action.subject.type}: the Google Maps APIs answer questions and accept no writes — nothing to perform` } };
+}

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

@@ -0,0 +1,87 @@
+import type { AddressComponent, GeocodeResult, Geometry, LatLng } from './googlemaps-types.js';
+/**
+ * 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 declare function stableHash(input: unknown): string;
+/** Normalize a free-text address for stable keying (lowercase, collapse ws). */
+export declare function normalizeAddress(address: string): string;
+/** Deterministic lat/lng in a plausible range derived from a seed string. */
+export declare function deterministicLatLng(seed: string): LatLng;
+export declare function viewportAround(loc: LatLng, delta?: number): Geometry['viewport'];
+/** A small named place dataset (canned, not real index lookups). */
+export type CannedPlace = {
+    place_id: string;
+    formatted_address: string;
+    location: LatLng;
+    types: string[];
+    components: AddressComponent[];
+    name: string;
+};
+/** Returns true for a query the twin deliberately maps to ZERO_RESULTS. */
+export declare function isZeroResultsQuery(q: string): boolean;
+/** Find a canned place by fuzzy name/address substring match. */
+export declare function findPlaceByText(query: string): CannedPlace | null;
+export declare function findPlaceById(placeId: string): CannedPlace | null;
+/** The country short_name (ccTLD-ish) for a canned place, for component filtering. */
+export declare function countryOf(p: CannedPlace): string | undefined;
+/** The locality long_name for a canned place (used in plus-code compound codes). */
+export declare function localityOf(p: CannedPlace): string;
+/** Nearest canned place to a lat/lng (for reverse geocoding). */
+export declare function findPlaceByLatLng(loc: LatLng): CannedPlace;
+export declare function allPlaces(): CannedPlace[];
+/** Localize a formatted_address for a `language` code (no-op for English/unknown). */
+export declare function localizeFormattedAddress(formatted_address: string, language: string | null | undefined): string;
+/** Build a faithful GeocodeResult from a canned place. */
+export declare function geocodeResultFromPlace(p: CannedPlace, locationType?: Geometry['location_type']): GeocodeResult;
+/**
+ * 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 declare function synthGeocodeResult(address: string): GeocodeResult;
+/** Great-circle distance (haversine) in meters between two points. */
+export declare function haversineMeters(a: LatLng, b: LatLng): number;
+/** Human "5.0 mi" / "1.2 km" text for a distance in meters (imperial default). */
+export declare function distanceText(meters: number, metric?: boolean): string;
+/** Human "15 mins" / "1 hour 5 mins" text for a duration in seconds. */
+export declare function durationText(seconds: number): string;
+/** Deterministic driving duration (seconds) for a distance — ~40 km/h average. */
+export declare function deterministicDuration(meters: number): number;
+/**
+ * A tiny polyline encoder (Google's Encoded Polyline Algorithm Format), used to
+ * produce a faithful `overview_polyline.points` for Directions responses.
+ */
+export declare function encodePolyline(points: LatLng[]): string;
+/** Deterministic elevation (meters) for a lat/lng. */
+export declare function deterministicElevation(loc: LatLng): number;
+/**
+ * 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 declare function deterministicTimeZone(loc: LatLng, timestamp?: number): {
+    timeZoneId: string;
+    timeZoneName: string;
+    rawOffset: number;
+    dstOffset: number;
+};
+export declare function encodePlusCode(loc: LatLng, codeLength?: number): string;
+export declare function plusCodeFor(loc: LatLng, localityName: string): {
+    global_code: string;
+    compound_code: string;
+};
+/** Deterministic next_page_token <-> offset codec for Places pagination. */
+export declare function encodePageToken(query: string, offset: number): string;
+export declare function decodePageToken(token: string): {
+    query: string;
+    offset: number;
+} | null;
+/** A faithful opening_hours block (weekday_text + periods) for a place. */
+export declare function openingHoursFor(p: CannedPlace): Record<string, unknown>;
+/** A faithful, deterministic set of reviews for a place. */
+export declare function reviewsFor(p: CannedPlace): Record<string, unknown>[];