@mapmap/react-native reference

npm install @mapmap/react-native@0.4.0

import { /* … */ } from "@mapmap/react-native";

class CustomRegionError extends Error { … }

import { CustomRegionError, createCustomRegionClient } from "@mapmap/react-native";

const regions = createCustomRegionClient({ apiKey: "snk_…" });
try {
  await regions.requestAndWait({ bbox: [-5, 50, 2, 55] });
} catch (err) {
  if (err instanceof CustomRegionError && err.code === "E_REGION_REFUSED") {
    console.log(err.problem, err.limit, err.value); // e.g. region-area-too-large
  } else {
    throw err;
  }
}

class MapmapNavMock extends SimpleEventEmitter<MapmapNavEvents> implements MapmapNavModule { … }

import { MapmapNavMock } from "@mapmap/react-native";

// The pure-TS stand-in for the native module, with the same API and events.
const nav = new MapmapNavMock({ territoryInstallDurationMs: 1000 });
await nav.init("snk_…");
nav.addListener("territoryProgress", (event) => console.log(event));
await nav.installTerritory("gb");

function addBridgeErrorListener(handle: MapmapNavEmitterLike<MapmapNavEvents>, listener: (event: BridgeError) => void): EventSubscription;

function addGuidanceListener(handle: MapmapNavEmitterLike<MapmapNavEvents>, listener: (event: GuidanceEvent) => void): EventSubscription;

function addTerritoryProgressListener(handle: MapmapNavEmitterLike<MapmapNavEvents>, listener: (event: TerritoryProgressEvent) => void): EventSubscription;

function addVoiceStateListener(handle: MapmapNavEmitterLike<MapmapNavEvents>, listener: (event: VoiceStateEvent) => void): EventSubscription;

function createCustomRegionClient(options: CustomRegionClientOptions): CustomRegionClient;

import { createCustomRegionClient, getMapmapNav, installCustomRegion } from "@mapmap/react-native";

const regions = createCustomRegionClient({ apiKey: "snk_…" });
const region = await regions.requestAndWait({ bbox: [-2.65, 51.42, -2.53, 51.49] });
const nav = getMapmapNav(false);
await nav.init("snk_…");
await installCustomRegion(nav, region); // a CustomRegion carries what the install needs

function createMapmapNavMock(options?: MapmapNavMockOptions): MapmapNavMock;

import { createMapmapNavMock } from "@mapmap/react-native";

const nav = createMapmapNavMock({ tickIntervalMs: 500, simulateReroute: false });
await nav.init("snk_…");
console.log(await nav.listAvailableTerritories());

function getMapmapNav(useMock: boolean, mockOptions?: MapmapNavMockOptions): MapmapNavHandle;

import { getMapmapNav } from "@mapmap/react-native";

// useMock: true in Expo Go, unit tests and UI work ahead of a native build.
const nav = getMapmapNav(false);
await nav.init("snk_…");
const sub = nav.addListener("guidance", (event) => console.log(event));
const { routes } = await nav.computeRoute({
  profile: "car",
  origin: { latitude: 51.5072, longitude: -0.1276 },
  destination: { latitude: 51.4545, longitude: -2.5879 },
});
console.log(routes.length);
await nav.startGuidance({ routeIndex: 0, source: { kind: "live" } });
sub.remove();

function installCustomRegion(nav: MapmapNavModule, region: CustomRegionInstall): Promise<void>;

import { createCustomRegionClient, getMapmapNav, installCustomRegion } from "@mapmap/react-native";

const nav = getMapmapNav(false);
await nav.init("snk_…");
const regions = createCustomRegionClient({ apiKey: "snk_…" });
const [county] = await regions.searchBoundaries({ q: "Rutland" });
if (county) {
  const region = await regions.requestAndWait({ boundaryId: county.boundaryId });
  await installCustomRegion(nav, region); // verified against the pinned key, then activated
}

function parseBoundaryCandidate(raw: Json): BoundaryCandidate;

function parseBoundaryFeature(raw: Json): BoundaryFeature;

function parseCustomRegion(raw: Json): CustomRegion;

interface MapmapNavEmitterLike<Events extends EventsMap>

interface MapmapNavModule

type AbortSignalLike = {
    readonly aborted: boolean;
    addEventListener(type: "abort", listener: () => void): void;
    removeEventListener(type: "abort", listener: () => void): void;
};

type BannerInstruction = {
    primary: string;
    secondary?: string;
    maneuverType: ManeuverType;
    roundaboutExit?: number;
    thenPrimary?: string;
    thenManeuverType?: ManeuverType;
};

type BoundaryCandidate = {
    boundaryId: string;
    name: string;
    nameEn?: string;
    adminLevel: number;
    country?: string;
    isoCode?: string;
    areaKm2: number;
    bbox: [number, number, number, number];
    territory: string;
    containsNear?: boolean;
    distanceKm?: number;
};

type BoundaryFeature = BoundaryCandidate & {
    geometry: RegionPolygon;
    simplification: {
        method: string;
        toleranceDeg: number;
        toleranceM: number;
        vertices: number;
        sourceVertices: number;
    };
    dataUpdated: string;
    licence: string;
    attribution: string;
};

type BoundarySearch = {
    q?: string;
    near?: {
        lat: number;
        lon: number;
    };
    level?: number | number[];
    country?: string;
    limit?: number;
};

type BridgeError = {
    code: BridgeErrorCode;
    message: string;
};

type BridgeErrorCode = "E_NOT_INITIALISED" | "E_INIT_FAILED" | "E_NETWORK" | "E_AUTH" | "E_TERRITORY_ALLOWANCE" | "E_TERRITORY_VERIFY" | "E_TERRITORY_NOT_FOUND" | "E_NO_TERRITORY" | "E_NO_ROUTE" | "E_GUIDANCE_ACTIVE" | "E_NO_GUIDANCE" | "E_REPLAY_CORPUS" | "E_CANCELLED" | "E_INTERNAL";

type CustomRegion = CustomRegionInstall & {
    version: string;
    displayName: string;
    bbox: [number, number, number, number];
    areaKm2: number;
    sourceTerritory: string;
    sourceVersion: string;
    dataUpdated: string;
    layers: CustomRegionLayerInfo[];
    installedBytes: number;
    downloadBytes: number;
    overlappingTerritories: string[];
    cached: boolean;
    boundary?: CustomRegionBoundary;
};

type CustomRegionBoundary = {
    boundaryId: string;
    name: string;
    nameEn?: string;
    adminLevel: number;
    country?: string;
    simplificationToleranceDeg: number;
    dataUpdated: string;
};

type CustomRegionClient = {
    requestCustomRegion(request: CustomRegionRequest, signal?: AbortSignalLike): Promise<CustomRegionJob>;
    getCustomRegionJob(jobId: string, signal?: AbortSignalLike): Promise<CustomRegionJob>;
    waitForCustomRegion(jobId: string, options?: WaitOptions): Promise<CustomRegion>;
    requestAndWait(request: CustomRegionRequest, options?: WaitOptions): Promise<CustomRegion>;
    searchBoundaries(search: BoundarySearch, signal?: AbortSignalLike): Promise<BoundaryCandidate[]>;
    getBoundary(boundaryId: string, signal?: AbortSignalLike): Promise<BoundaryFeature>;
};

type CustomRegionClientOptions = {
    apiKey: string;
    gatewayBaseUrl?: string;
    fetch?: FetchLike;
};

type CustomRegionErrorCode = "E_REGION_REFUSED" | "E_REGION_INVALID" | "E_REGION_FAILED" | "E_REGION_TIMEOUT" | "E_REGIONS_NOT_ENABLED" | "E_BOUNDARIES_NOT_ENABLED" | "E_NOT_FOUND" | "E_AUTH" | "E_QUOTA" | "E_CANCELLED" | "E_NETWORK";

type CustomRegionInstall = {
    territoryId: string;
    indexUrl: string;
    indexSigUrl: string;
};

type CustomRegionJob = {
    id: string;
    status: CustomRegionJobStatus;
    resultUrl: string;
    unitsCharged: number;
    refunded: boolean;
    error?: string;
    region?: CustomRegion;
};

type CustomRegionJobStatus = "queued" | "running" | "succeeded" | "failed";

type CustomRegionLayer = "valhalla-tiles" | "pmtiles" | "geocode-index" | "style";

type CustomRegionLayerInfo = {
    kind: string;
    installedBytes: number;
    downloadBytes: number;
};

type CustomRegionRequest = ({
    bbox: [west: number, south: number, east: number, north: number];
    polygon?: never;
    boundaryId?: never;
} | {
    polygon: RegionPolygon;
    bbox?: never;
    boundaryId?: never;
} | {
    boundaryId: string;
    bbox?: never;
    polygon?: never;
}) & {
    layers?: CustomRegionLayer[];
    source?: string;
    webhookUrl?: string;
};

type FetchLike = (url: string, init: {
    method: string;
    headers: Record<string, string>;
    body?: string;
    signal?: AbortSignalLike;
}) => Promise<{
    status: number;
    text(): Promise<string>;
}>;

type GuidanceEvent = {
    state: "navigating" | "rerouting" | "arrived";
    location: LatLng & {
        bearingDegrees: number;
        speedMps: number;
    };
    banner?: BannerInstruction;
    distanceToManeuverMeters: number;
    remainingDistanceMeters: number;
    remainingDurationSeconds: number;
    etaEpochMs: number;
    isOffRoute: boolean;
};

type GuidanceOptions = {
    routeIndex: number;
    source: LocationSource;
};

type LatLng = {
    latitude: number;
    longitude: number;
};

type LocationSource = {
    kind: "live";
} | {
    kind: "replay";
    corpusPath: string;
    speedMultiplier?: number;
};

type Maneuver = {
    type: ManeuverType;
    instruction: string;
    distanceMeters: number;
    position: LatLng;
    roundaboutExit?: number;
};

type ManeuverType = "depart" | "turn-left" | "turn-right" | "slight-left" | "slight-right" | "sharp-left" | "sharp-right" | "uturn" | "straight" | "merge" | "on-ramp" | "off-ramp" | "fork-left" | "fork-right" | "roundabout" | "arrive";

type MapmapNavEvents = {
    territoryProgress: (event: TerritoryProgressEvent) => void;
    guidance: (event: GuidanceEvent) => void;
    voiceState: (event: VoiceStateEvent) => void;
    bridgeError: (event: BridgeError) => void;
};

type MapmapNavHandle = MapmapNavModule & MapmapNavEmitterLike<MapmapNavEvents>;

type MapmapNavMockOptions = {
    tickIntervalMs?: number;
    territoryInstallDurationMs?: number;
    simulateReroute?: boolean;
    routeProvider?: (request: RouteRequest) => Promise<RouteResult | null>;
};

type NativeMapmapNavModule = MapmapNavModule & MapmapNavEmitterLike<MapmapNavEvents>;

type Position = [number, number];

type RegionPolygon = {
    type: "Polygon";
    coordinates: Position[][];
} | {
    type: "MultiPolygon";
    coordinates: Position[][][];
};

type Route = {
    index: number;
    geometry: LatLng[];
    distanceMeters: number;
    durationSeconds: number;
    maneuvers: Maneuver[];
};

type RouteProfile = "car" | "bicycle" | "walking";

type RouteRequest = {
    profile: RouteProfile;
    origin: LatLng;
    destination: LatLng;
    alternatives?: number;
};

type RouteResult = {
    routes: Route[];
};

type SearchResult = {
    name: string;
    address: string;
    position: LatLng;
    distanceMeters?: number;
};

type TerritoryInfo = {
    id: string;
    name: string;
    version: string;
    sizeOnDiskBytes: number;
    active: boolean;
};

type TerritoryPhase = "downloading" | "verifying" | "activating" | "done" | "failed" | "cancelled";

type TerritoryProgressEvent = {
    territoryId: string;
    phase: TerritoryPhase;
    bytesDone: number;
    bytesTotal: number;
    error?: BridgeError;
};

type TerritorySummary = {
    id: string;
    name: string;
    sizeBytes: number;
    version: string;
};

type VoiceStateEvent = {
    muted: boolean;
    volume: number;
    speaking: boolean;
};

type WaitOptions = {
    intervalMs?: number;
    maxIntervalMs?: number;
    timeoutMs?: number;
    signal?: AbortSignalLike;
    onUpdate?: (job: CustomRegionJob) => void;
};

const HOSTED_REGION_KEY_HEX = "6f60f17bc31be2f7696cb957b2188416741e09cb3e7bdec2719fe553213be107";

const MapmapNav: NativeMapmapNavModule;