@volter/twin-mapbox

Legacy connector helpers: this package still has callable helpers using the retired v1 syncPull API. Those paths require migration before use on the current kernel; older helper descriptions below do not establish current compatibility. Check the generated index for protocol standing and use the shared model for current state semantics.

A local Mapbox API twin — offline, deterministic replicas of the api.mapbox.com surface in vendor-faithful GeoJSON FeatureCollection shapes, with the real access_token= gate and stateful Datasets/Styles/Tokens/Tilesets/ Uploads on the shared kernel event log. An unmodified HTTP/SDK client (e.g. @mapbox/mapbox-sdk) points at it and gets Mapbox-correct responses.

world-mapbox serve [--port N] [--root DIR] [--read-only]
world-mapbox conformance [--root DIR]

Coverage

The capability manifest (src/mapbox-capabilities.ts) is an honest partial denominator across the Mapbox API families. A broad core slice is done (each with a failable, deterministic verify asserting response values plus the vendor's negative 4xx path); the long tail (parameters/options) is honest todo.

Deterministic canned data, NOT real geodata. A local twin cannot reproduce Mapbox's geocoding index, road network, or rendered tiles. It returns faithful response shapes with stable, deterministic values: a given query always maps to the same canned result. Known places (123 Market St, Los Angeles, New York, London, Tokyo) resolve to a small canned dataset; any other well-formed query is synthesized deterministically from its hash so the twin never falsely empties a valid request.

Auth. Every endpoint gates on the access_token= query parameter (or Authorization: Bearer). Missing → 401 {"message":"Not Authorized - No Token"}; malformed → 401 {"message":"Not Authorized - Invalid Token"}; sentinel tokens exercise 429 (rate limit) and 403 (forbidden). In-process callers that model no headers get implicit auth so offline flows keep working.

Modeled (done):

• Geocoding v6. search/geocode/v6/forward (free-text + structured input), …/reverse, and …/batch — FeatureCollection of Features with geometry.type:"Point", coordinates:[lng,lat], and the full v6 properties (mapbox_id, feature_type, name, name_preferred, full_address, address_line1, place_formatted, and the context block keyed by place/region{region_code,name}/postcode/country). This matches the QA-stack mockMapboxGeocode contract exactly.
• Legacy Geocoding v5. geocoding/v5/mapbox.places/{query}.json forward + reverse with the v5 Feature shape (place_name, text, center, context[] with short_code).
• Search Box. suggest (with session_token), retrieve/{id}, category/{c}, forward, reverse.
• Directions. directions/v5/mapbox/{profile}/{coords} — code:"Ok", routes[] (distance/duration/geometry polyline-or-GeoJSON/legs[]), waypoints[]; per-profile validation, multi-leg, InvalidInput (422).
• Matrix. directions-matrix/v1/… — durations/distances grids, sources/destinations subsets, per-profile coordinate cap (25 / 10).
• Isochrone. isochrone/v1/… — Polygon (or LineString) contour features with contour/color/metric properties; up-to-four-contour validation.
• Map Matching. matching/v5/… — matchings[] + tracepoints[].
• Optimization. v1 optimized-trips/v1/… (trips[] + ordered waypoints), v2 optimized-trips/v2 submission (202 processing id).
• Tilequery. v4/{tileset}/tilequery/{lng,lat}.json — Point features with tilequery:{distance,geometry,layer}.
• Static Images / TileJSON / Fonts. Static-image metadata (size, size limit), v4/{tileset}.json TileJSON, font-stack list + glyph-range metadata.
• Datasets (stateful). Create/read/list/update/delete + feature PUT/GET/DELETE — folded from the kernel event log (create→read-back→delete→404).
• Styles (stateful). Create (201)/read/list/update/delete with the full style object (version/layers/sources/metadata/owner/created/modified); unknown id → 404 Style not found.
• Tokens (stateful). Create (pk./sk. by scope)/list/update/delete + scopes catalog.
• Tilesets (stateful). Create/list/delete (MTS recipe validation).
• Uploads (stateful). S3 staging credentials, create (201)/status/list/delete.
• Connector. Injected-client pulls (pullMapboxGeocodes, pullMapboxStyles), idempotent; pushPendingMapboxActions confirms local geocode seeds.

Not yet modeled (honest todo): geocoding proximity/bbox/types/worldview/ routable-points biasing, v5 permanent/autocomplete, Search Box rich POI attributes, Directions steps/annotations/alternatives/exclude/voice, Matrix fallback_speed/approaches, Isochrone denoise/generalize, Map Matching timestamps/radiuses, Optimization v2 solution retrieval, Tilequery layer filtering, Static Image overlays, Styles sprite/embed, temporary/URL-restricted tokens, Tileset publish jobs + sources, dataset feature bbox/pagination, the Routes API (New), Movement/Boundaries/Vision/account-usage products; and the binary payloads — deterministic raster bytes at the Static Image URLs, Mapbox Vector Tile protobuf bytes at the tile URLs, and SDF glyph protobuf bytes for a glyph range (all three return only metadata today).

Architecture

State lives in the @volter/world-core event/action log (geocode overrides + the stateful Datasets/Styles/Tokens/Tilesets/Uploads resources, with deletes as a _deleted overlay since the log is append-only); there is no ad-hoc store. The serve path makes no real network calls; connector functions accept injected executors for real Mapbox I/O and are not used by the local handler. This is an API-first vendor with no operator-facing dashboard, so the pack ships no UI mirror — coverage is API + connector.