@volter/twin-googlemaps 0.1.0

package/src/googlemaps-types.ts

@@ -0,0 +1,47 @@
+export type GoogleMapsRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  root?: string;
+  readOnly?: boolean;
+  occurredAt?: string;
+  headers?: Record<string, string>;
+};
+
+export type GoogleMapsResponse = { status: number; body: unknown };
+
+/** Web-service ("Maps") status enum shared across geocode/directions/etc. */
+export type MapsStatus =
+  | 'OK'
+  | 'ZERO_RESULTS'
+  | 'OVER_DAILY_LIMIT'
+  | 'OVER_QUERY_LIMIT'
+  | 'REQUEST_DENIED'
+  | 'INVALID_REQUEST'
+  | 'MAX_ELEMENTS_EXCEEDED'
+  | 'MAX_WAYPOINTS_EXCEEDED'
+  | 'MAX_ROUTE_LENGTH_EXCEEDED'
+  | 'NOT_FOUND'
+  | 'UNKNOWN_ERROR';
+
+export type LatLng = { lat: number; lng: number };
+
+export type Viewport = { northeast: LatLng; southwest: LatLng };
+
+export type AddressComponent = { long_name: string; short_name: string; types: string[] };
+
+export type Geometry = {
+  location: LatLng;
+  location_type: 'ROOFTOP' | 'RANGE_INTERPOLATED' | 'GEOMETRIC_CENTER' | 'APPROXIMATE';
+  viewport: Viewport;
+  bounds?: Viewport;
+};
+
+export type GeocodeResult = {
+  address_components: AddressComponent[];
+  formatted_address: string;
+  geometry: Geometry;
+  place_id: string;
+  types: string[];
+  plus_code?: { global_code: string; compound_code: string };
+};

package/src/index.ts

@@ -0,0 +1,124 @@
+export { handleGoogleMapsTwinRequest } from './googlemaps-twin.ts';
+export { createGoogleMapsTwinFetch, createGoogleMapsTwinServer, type GoogleMapsTwinFetchOptions } from './googlemaps-server.ts';
+export {
+  GOOGLEMAPS_API_BASE,
+  googleMapsRequestForAction,
+  liveGoogleMapsExecute,
+  pullGoogleMapsGeocodes,
+  pullGoogleMapsPlaces,
+  pushGoogleMapsAction,
+  syncGoogleMapsFromReal,
+} from './googlemaps-connector.ts';
+export type { GoogleMapsExecute } from './googlemaps-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveGoogleMapsExecute` routes every live
+// request through. The mechanism is the kernel's (`@volter/world-core` → rateBudget.ts); these are this
+// vendor's numbers and the typed bindings around them.
+export {
+  GOOGLEMAPS_BUDGET_CEILING,
+  GOOGLEMAPS_BUDGET_MAX_RETRY_AFTER_S,
+  GOOGLEMAPS_BUDGET_WINDOW_MS,
+  GOOGLEMAPS_CALL_WEIGHTS,
+  GOOGLEMAPS_RATE_BUDGET,
+  GoogleMapsBudget,
+  GoogleMapsBudgetError,
+  googleMapsBudgetPath,
+  googleMapsCallWeight,
+  splitGoogleMapsPath,
+} from './googlemaps-budget.ts';
+export type {
+  GoogleMapsBudgetErrorKind,
+  GoogleMapsBudgetOptions,
+  GoogleMapsBudgetReservation,
+  GoogleMapsBudgetSnapshot,
+} from './googlemaps-budget.ts';
+export {
+  allPlaces,
+  deterministicDuration,
+  deterministicElevation,
+  deterministicLatLng,
+  deterministicTimeZone,
+  distanceText,
+  durationText,
+  encodePolyline,
+  findPlaceById,
+  findPlaceByLatLng,
+  findPlaceByText,
+  geocodeResultFromPlace,
+  haversineMeters,
+  isZeroResultsQuery,
+  normalizeAddress,
+  stableHash,
+  synthGeocodeResult,
+  viewportAround,
+} from './googlemaps-data.ts';
+export type { CannedPlace } from './googlemaps-data.ts';
+export type {
+  AddressComponent,
+  GeocodeResult,
+  Geometry,
+  GoogleMapsRequest,
+  GoogleMapsResponse,
+  LatLng,
+  MapsStatus,
+  Viewport,
+} from './googlemaps-types.ts';
+
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { GOOGLEMAPS_RATE_BUDGET as RATE_BUDGET } from './googlemaps-budget.ts';
+
+import { performGoogleMapsAction, syncGoogleMapsFromRemote } from './googlemaps-connector.ts';
+
+export const pack: TwinPack = {
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
+  // state system. Moved 2026-09-08. The Google Maps APIs answer questions and accept no writes, so `perform`
+  // settles every entry with that reason and only `refresh` ever crosses.
+  protocol: '2',
+  refresh: { every: '1h', onDemand: { atMost: '60s' } }, // an address's geocode moves rarely; there are no webhooks
+  stateSystem: { perform: performGoogleMapsAction, refresh: syncGoogleMapsFromRemote },
+  // the round trip seeds one address's geocode — the twin's own door, because the vendor has no writable
+  // surface at all
+  roundTrip: { method: 'POST', path: '/twin/geocode?key=round-trip', body: { address: '1600 Amphitheatre Parkway, Mountain View, CA', result: { formatted_address: '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA', geometry: { location: { lat: 37.4224, lng: -122.0842 } }, place_id: 'ChIJ_round_trip', types: ['street_address'] } } },
+  // a geocode stands alone — no subject here names another, so there is nothing for rule 5 to follow
+  references: [],
+  // The LEGACY endpoints this connector calls (Geocoding, Place Details) authenticate with `key=`
+  // in the QUERY STRING. Google's newer surfaces (Places API New, Address Validation) accept
+  // `X-Goog-Api-Key` instead — if this pack ever pulls through those, the strategy becomes a header
+  // and this line is where that is said (googlemaps-auth.ts documents both).
+  auth: { in: 'query', name: 'key' },
+  parityOrigin: 'http://twin',
+  // shapeParity is NOT held, for a structural reason rather than a divergence: the Geocoding API has no
+  // inventory to enumerate — you ask it about an address, and nothing lists what you have asked. A refresh
+  // into a fresh root therefore has nothing to ask about, so the gate's comparison has no ground here.
+  vendor: 'googlemaps',
+  // The SAME object googlemaps-budget.ts declares at module load — one source of truth, so
+  // registering the pack and importing the connector arm identical numbers.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'crud',
+  bin: 'world-googlemaps',
+  // The subject types the twin SERVES over its own API — the R2 resource-level claim.
+  // `place` is deliberately NOT here: it is a connector-side projection that only
+  // `pullGoogleMapsPlaces` / `syncGoogleMapsFromReal` fold in from a real account through an
+  // injected client, and no route reads it back — Place Details answers from the canned
+  // corpus (`findPlaceById` over googlemaps-data.ts's PLACES), never from stored state.
+  // `geocode` stays because the twin both writes it (POST /twin/geocode) and serves it
+  // (the Geocoding route's stateful override); `audit` because GET /twin/audit reads it.
+  resources: ['geocode', 'audit'],
+  specSource: 'Google Maps Platform web-service APIs (Geocoding, Distance Matrix, Directions, Places + Places API New, Roads, Time Zone, Elevation, Geolocation, Address Validation, Static Maps, Street View Static) — deterministic canned data in faithful response shapes',
+  description: 'Google Maps Platform twin — deterministic, offline replicas of the Maps web-service APIs in vendor-faithful response shapes with the real status semantics + API-key gate.',
+  // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31): the official Node client, the `@googlemaps/` scope, the
+  // GOOGLEMAPS_* credential stem, and maps.googleapis.com — one of several *.googleapis.com
+  // hosts kept as separate vendors rather than one 'google' (see webrisk, gemini).
+  adoption: {
+    // Google's official Maps Platform Python client (googlemaps/google-maps-services-python).
+    pypi: ['googlemaps'],
+    sdks: ['@googlemaps/google-maps-services-js'],
+    scopes: ['@googlemaps/'],
+    envStems: ['GOOGLEMAPS'],
+  },
+  hosts: [{ host: 'maps.googleapis.com' }],
+  browserRouting: { apiPathPrefix: '/maps/api/', loaderHost: 'https://maps.googleapis.com' },
+};
+// registered at import: the kernel learns the pack's state system (protocol 2)
+registerPack(pack);