@ingissa/navcore-types 1.0.1

package/dist/builder.d.ts

@@ -0,0 +1,73 @@
+/**
+ * CustomRouteBuilder — Types for building custom routes
+ *
+ * Build routes with unlimited waypoints, GPX/GeoJSON import/export,
+ * and configurable chunking strategies.
+ */
+import type { Coord } from './core';
+/** Options when adding a waypoint */
+export interface WaypointOptions {
+    /** Whether this is a silent waypoint (no instruction generated) */
+    silent?: boolean;
+    /** Optional name/label for the waypoint */
+    name?: string;
+}
+/** How to connect waypoints when building */
+export interface BuildOptions {
+    /** Connection mode between waypoints */
+    connectionMode?: 'ROUTED' | 'STRAIGHT' | 'MIXED';
+    /** Chunk overlap strategy for multi-segment API calls */
+    chunkStrategy?: 'OVERLAP_1' | 'OVERLAP_2';
+    /** Maximum waypoints per API call (provider-specific, default 25) */
+    maxWaypointsPerChunk?: number;
+}
+/** A waypoint in the custom route */
+export interface CustomWaypoint {
+    id: string;
+    coord: Coord;
+    options?: WaypointOptions;
+}
+/** The built custom route */
+export interface CustomRoute {
+    /** Full stitched geometry */
+    geometry: Coord[];
+    /** Individual waypoints */
+    waypoints: CustomWaypoint[];
+    /** Total distance in metres */
+    distance: number;
+    /** Total duration in seconds */
+    duration: number;
+}
+/** GeoJSON FeatureCollection (minimal typing for zero-dep constraint) */
+export interface FeatureCollection {
+    type: 'FeatureCollection';
+    features: Array<{
+        type: 'Feature';
+        geometry: {
+            type: string;
+            coordinates: Coord[] | Coord;
+        };
+        properties: Record<string, unknown>;
+    }>;
+}
+/** The builder interface */
+export interface CustomRouteBuilderInterface {
+    /** Add a waypoint at the end of the route */
+    addWaypoint(coord: Coord, options?: WaypointOptions): string;
+    /** Insert a waypoint after an existing one */
+    insertWaypoint(coord: Coord, afterId: string): string;
+    /** Remove a waypoint by ID */
+    removeWaypoint(id: string): void;
+    /** Move an existing waypoint to a new coordinate */
+    moveWaypoint(id: string, newCoord: Coord): void;
+    /** Build the route using the configured directions provider */
+    build(options?: BuildOptions): Promise<CustomRoute>;
+    /** Import waypoints from a GPX string */
+    fromGPX(gpxString: string): void;
+    /** Import waypoints from a GeoJSON FeatureCollection */
+    fromGeoJSON(geojson: FeatureCollection): void;
+    /** Export the current route as GeoJSON */
+    toGeoJSON(): FeatureCollection;
+    /** Export the current route as GPX */
+    toGPX(): string;
+}

package/dist/builder.js

@@ -0,0 +1,7 @@
+/**
+ * CustomRouteBuilder — Types for building custom routes
+ *
+ * Build routes with unlimited waypoints, GPX/GeoJSON import/export,
+ * and configurable chunking strategies.
+ */
+export {};

package/dist/core.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Core types used throughout the NavCore SDK.
+ */
+/** [longitude, latitude] — Mapbox/GeoJSON order */
+export type Coord = [number, number];
+/** GPS update from the device */
+export interface NavGpsUpdate {
+    coord: Coord;
+    accuracy: number | null;
+    bearing: number | null;
+    speed: number;
+    timestamp: number;
+}
+/** Full navigation engine state snapshot */
+export interface NavCoreState {
+    snappedCoord: Coord | null;
+    ghostCoord: Coord | null;
+    rawGpsCoord: Coord | null;
+    bearing: number;
+    rawGpsBearing: number | null;
+    routeIndex: number;
+    anchorRouteIndex: number | null;
+    distanceToRoute: number;
+    corridor: number;
+    confidence: number;
+    isOffRoute: boolean;
+    navFsmState: string;
+    progressIndex: number;
+    hasArrived: boolean;
+    rejoinCandidate: {
+        coord: Coord;
+        index: number;
+    } | null;
+    confidenceCone: {
+        center: Coord;
+        bearing: number;
+        angle: number;
+        length: number;
+    } | null;
+    alertState: 'NONE' | 'DEVIATING' | 'RECALCULATING' | 'REJOINING' | 'REJOINED';
+    detourMode: 'NONE' | 'FREE' | 'COMMITTED';
+    detourCommitProgress: number;
+    distanceToNextInstruction: number | null;
+    distanceToDestination: number | null;
+    nextInstrIdx: number | null;
+    nextInstructionIndex: number | null;
+    isGpsStale: boolean;
+    gpsAgeMs: number;
+    currentSpeed: number;
+    licenseStatus: NavLicenseInfo;
+    stability?: {
+        oscillation: number;
+        drift: number;
+        jump: number;
+    };
+}
+/** Navigation lifecycle states */
+export type NavLifecycleState = 'IDLE' | 'OVERVIEW' | 'APPROACHING_ROUTE' | 'ON_ROUTE' | 'DEVIATING' | 'OFF_ROUTE' | 'REROUTING' | 'REJOINING' | 'REJOINED' | 'FAILED';
+/** License validation status */
+export type LicenseStatus = 'VALID' | 'INVALID' | 'EXPIRED' | 'MISSING';
+/** License info returned by the engine */
+export interface NavLicenseInfo {
+    plan: 'free' | 'pro' | 'ai';
+    limitations: string[];
+}
+/** Engine configuration (all optional with defaults) */
+export interface NavOptions {
+    baseCorridorMeters?: number;
+    speedFactor?: number;
+    maxCorridorMeters?: number;
+    gpsAccuracyFactor?: number;
+    offRouteConfirmMs?: number;
+    rejoinConfirmMs?: number;
+    rejoinCooldownMs?: number;
+    startupGraceMs?: number;
+    betaCorrection?: number;
+    gpsAgeCapSeconds?: number;
+    gpsStaleMs?: number;
+    drMaxAgeMs?: number;
+    detourCommitMs?: number;
+    bearingSmoothingAlpha?: number;
+    detourBearingThreshold?: number;
+    lookAheadSeconds?: number;
+    minLookAheadMeters?: number;
+    maxLookAheadMeters?: number;
+    arrivalThresholdMeters?: number;
+    isCircuit?: boolean;
+    kalmanQ?: number;
+    kalmanRBase?: number;
+    licenseKey?: string;
+}
+/** Navigation instruction (turn-by-turn step) */
+export interface NavInstruction {
+    location: Coord;
+    geometryIndex: number;
+    text?: string;
+    instruction?: string;
+    cumulativeOffset?: number;
+}
+/** Deviation event emitted when vehicle goes off-route */
+export interface DeviationEvent {
+    anchorIndex: number;
+    ghostCoord: Coord;
+    rejoinTarget: {
+        coordinates: Coord;
+        index: number;
+    };
+}
+/** Alert event emitted on state changes */
+export interface AlertEvent {
+    type: NavCoreState['alertState'];
+    message: string | null;
+}
+/** Feature key for license gating */
+export type FeatureKey = 'advanced_snapping' | 'dead_reckoning' | 'route_offset' | 'progress_tracking' | 'advanced_bearing' | 'compound_deviation' | 'nav_ai';
+/** Route snapping result */
+export interface SnapResult {
+    idx: number;
+    dist: number;
+    proj: Coord;
+}
+/** Dead reckoning prediction */
+export interface DRPrediction {
+    predictedCoord: Coord;
+    isActive: boolean;
+    ageMs: number;
+}
+/** Dead reckoning anchor point */
+export interface DRAnchor {
+    coord: Coord;
+    idx: number;
+    ts: number;
+}
+/** Line style for renderer adapters */
+export interface LineStyle {
+    color?: string;
+    width?: number;
+    opacity?: number;
+    dashPattern?: number[];
+}
+/** Camera target for renderer adapters */
+export interface CameraTarget {
+    coord: Coord;
+    bearing: number;
+    zoom?: number;
+    pitch?: number;
+}

package/dist/core.js

@@ -0,0 +1,4 @@
+/**
+ * Core types used throughout the NavCore SDK.
+ */
+export {};

package/dist/directions.d.ts

@@ -0,0 +1,67 @@
+/**
+ * DirectionsProvider — Data source contract
+ *
+ * Any directions API (Mapbox, OSRM, Valhalla, or a custom server)
+ * implements this interface to provide routing data to NavCore.
+ *
+ * The provider MUST handle waypoint chunking internally if the
+ * underlying API has waypoint limits. NavCore imposes no limit.
+ */
+import type { Coord } from './core';
+/** Options for route calculation */
+export interface RouteOptions {
+    /** Driving profile: 'driving' | 'driving-traffic' | 'cycling' | 'walking' */
+    profile?: string;
+    /** Request alternatives */
+    alternatives?: boolean;
+    /** Include step-by-step instructions */
+    steps?: boolean;
+    /** Geometry format: 'geojson' | 'polyline' | 'polyline6' */
+    geometries?: string;
+    /** Route overview level: 'full' | 'simplified' | 'false' */
+    overview?: string;
+    /** Language code for instructions (e.g. 'en', 'fr', 'nl') */
+    language?: string;
+}
+/** A single route leg between two waypoints */
+export interface RouteLeg {
+    distance: number;
+    duration: number;
+    steps?: RouteStep[];
+}
+/** A single step within a leg */
+export interface RouteStep {
+    distance: number;
+    duration: number;
+    geometry: Coord[];
+    maneuver: {
+        type: string;
+        modifier?: string;
+        location: Coord;
+        bearing_before: number;
+        bearing_after: number;
+        instruction?: string;
+    };
+    name?: string;
+}
+/** Complete route result from a directions provider */
+export interface RouteResult {
+    /** Full route geometry */
+    geometry: Coord[];
+    /** Total distance in metres */
+    distance: number;
+    /** Total duration in seconds */
+    duration: number;
+    /** Individual legs */
+    legs: RouteLeg[];
+    /** Raw provider response (for debugging) */
+    raw?: unknown;
+}
+/** The provider interface */
+export interface DirectionsProvider {
+    /**
+     * Calculate a route through the given waypoints.
+     * Must handle chunking internally if the provider has waypoint limits.
+     */
+    getRoute(waypoints: Coord[], options?: RouteOptions): Promise<RouteResult>;
+}

package/dist/directions.js

@@ -0,0 +1,10 @@
+/**
+ * DirectionsProvider — Data source contract
+ *
+ * Any directions API (Mapbox, OSRM, Valhalla, or a custom server)
+ * implements this interface to provide routing data to NavCore.
+ *
+ * The provider MUST handle waypoint chunking internally if the
+ * underlying API has waypoint limits. NavCore imposes no limit.
+ */
+export {};

package/dist/exam.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ExamInstruction — Klaroways-specific extension
+ *
+ * Extends the base NavInstruction with exam-specific scoring fields,
+ * trigger conditions, and mandatory/optional classification.
+ */
+import type { NavInstruction } from './core';
+/** Actions the examiner evaluates */
+export type ExamAction = 'MIRROR_CHECK' | 'SIGNAL' | 'OBSERVATION' | 'SPEED_REDUCE' | 'BLIND_SPOT_CHECK' | 'YIELD' | 'FULL_STOP' | 'LANE_POSITION';
+/** Condition that must be met for the instruction to trigger */
+export interface TriggerCondition {
+    minSpeedKmh?: number;
+    maxSpeedKmh?: number;
+    timeOfDay?: {
+        from: string;
+        to: string;
+    };
+}
+/** Exam instruction extending the base navigation instruction */
+export interface ExamInstruction extends NavInstruction {
+    /** The action being evaluated */
+    examAction: ExamAction;
+    /** Points awarded/deducted for this instruction */
+    pointValue: number;
+    /** Whether this instruction is mandatory (failure = immediate fail) */
+    mandatory: boolean;
+    /** Optional note for the examiner */
+    examNote?: string;
+    /** Condition gating when this instruction activates */
+    triggerCondition?: TriggerCondition;
+    /** Multilingual instruction group ID (from Convex backend) */
+    instructionGroupId?: string;
+}
+/** Hazard zone definition for exam routes */
+export interface ExamHazardZone {
+    /** Center coordinate of the hazard zone */
+    center: [number, number];
+    /** Radius in metres */
+    radiusM: number;
+    /** Type of hazard */
+    type: 'SCHOOL_ZONE' | 'HOSPITAL' | 'PEDESTRIAN_CROSSING' | 'TRAM_TRACKS' | 'RESIDENTIAL';
+    /** Required actions within this zone */
+    requiredActions: ExamAction[];
+    /** Maximum allowed speed in km/h */
+    maxSpeedKmh?: number;
+}

package/dist/exam.js

@@ -0,0 +1,7 @@
+/**
+ * ExamInstruction — Klaroways-specific extension
+ *
+ * Extends the base NavInstruction with exam-specific scoring fields,
+ * trigger conditions, and mandatory/optional classification.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @navcore/types — Shared type definitions
+ *
+ * This package contains all public interfaces and types for the NavCore SDK.
+ * It has ZERO runtime dependencies.
+ */
+export * from './core';
+export * from './renderer';
+export * from './directions';
+export * from './builder';
+export * from './exam';

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @navcore/types — Shared type definitions
+ *
+ * This package contains all public interfaces and types for the NavCore SDK.
+ * It has ZERO runtime dependencies.
+ */
+export * from './core';
+export * from './renderer';
+export * from './directions';
+export * from './builder';
+export * from './exam';

package/dist/renderer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * NavCoreRenderer — Adapter contract
+ *
+ * Any map renderer (Mapbox, MapLibre, Leaflet, or a headless test harness)
+ * implements this interface to receive rendering commands from NavCore.
+ *
+ * NavCore NEVER depends on a specific renderer — adapters depend on core,
+ * core never depends on adapters.
+ */
+import type { Coord, LineStyle, CameraTarget } from './core';
+export interface NavCoreRenderer {
+    /** Update the vehicle marker position and rotation */
+    setVehiclePosition(coord: Coord, bearing: number): void;
+    /** Draw or update the main route polyline */
+    setRouteGeometry(coords: Coord[], style?: LineStyle): void;
+    /** Draw or clear the detour/reroute polyline */
+    setDetourGeometry(coords: Coord[] | null, style?: LineStyle): void;
+    /** Show or hide the ghost vehicle (on-route projection when off-route) */
+    setGhostPosition(coord: Coord | null, bearing: number): void;
+    /** Set the camera center, bearing, and optional zoom */
+    setCameraTarget(coord: Coord, bearing: number, zoom?: number): void;
+    /** Animate the camera to a target over durationMs */
+    animateCamera(target: CameraTarget, durationMs: number): void;
+    /** Teardown — release all map resources */
+    destroy(): void;
+}
+/**
+ * HeadlessRenderer — No-op implementation for CI/CD testing.
+ * Records all calls for assertion in integration tests.
+ */
+export declare class HeadlessRenderer implements NavCoreRenderer {
+    readonly calls: Array<{
+        method: string;
+        args: unknown[];
+    }>;
+    setVehiclePosition(coord: Coord, bearing: number): void;
+    setRouteGeometry(coords: Coord[], style?: LineStyle): void;
+    setDetourGeometry(coords: Coord[] | null, style?: LineStyle): void;
+    setGhostPosition(coord: Coord | null, bearing: number): void;
+    setCameraTarget(coord: Coord, bearing: number, zoom?: number): void;
+    animateCamera(target: CameraTarget, durationMs: number): void;
+    destroy(): void;
+}

package/dist/renderer.js

@@ -0,0 +1,39 @@
+/**
+ * NavCoreRenderer — Adapter contract
+ *
+ * Any map renderer (Mapbox, MapLibre, Leaflet, or a headless test harness)
+ * implements this interface to receive rendering commands from NavCore.
+ *
+ * NavCore NEVER depends on a specific renderer — adapters depend on core,
+ * core never depends on adapters.
+ */
+/**
+ * HeadlessRenderer — No-op implementation for CI/CD testing.
+ * Records all calls for assertion in integration tests.
+ */
+export class HeadlessRenderer {
+    constructor() {
+        this.calls = [];
+    }
+    setVehiclePosition(coord, bearing) {
+        this.calls.push({ method: 'setVehiclePosition', args: [coord, bearing] });
+    }
+    setRouteGeometry(coords, style) {
+        this.calls.push({ method: 'setRouteGeometry', args: [coords, style] });
+    }
+    setDetourGeometry(coords, style) {
+        this.calls.push({ method: 'setDetourGeometry', args: [coords, style] });
+    }
+    setGhostPosition(coord, bearing) {
+        this.calls.push({ method: 'setGhostPosition', args: [coord, bearing] });
+    }
+    setCameraTarget(coord, bearing, zoom) {
+        this.calls.push({ method: 'setCameraTarget', args: [coord, bearing, zoom] });
+    }
+    animateCamera(target, durationMs) {
+        this.calls.push({ method: 'animateCamera', args: [target, durationMs] });
+    }
+    destroy() {
+        this.calls.push({ method: 'destroy', args: [] });
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ingissa/navcore-types",
+  "version": "1.0.1",
+  "description": "Shared type definitions for the NavCore SDK ecosystem.",
+  "author": "Ingissa <8abnav@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://navcore-web.vercel.app/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ingissa/ingissa-navcore-examples.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ingissa/ingissa-navcore-examples/issues"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  }
+}