@ingissa/navcore-core 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,279 @@
+# @ingissa/navcore-core
+
+> **The navigation layer you own.** A framework-agnostic, zero-dependency navigation engine that runs everywhere — browsers, React Native, Node.js, and CI/CD.
+
+[![npm version](https://img.shields.io/npm/v/@ingissa/navcore-core)](https://www.npmjs.com/package/@ingissa/navcore-core)
+[![License](https://img.shields.io/badge/license-MIT%20%2F%20Commercial-purple)](https://navcore.dev/pricing)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
+[![Zero deps](https://img.shields.io/badge/runtime_deps-0-brightgreen)](https://www.npmjs.com/package/@ingissa/navcore-core)
+
+---
+
+## Why NavCore?
+
+| Feature | NavCore | Mapbox Nav SDK | Google Maps |
+|---|---|---|---|
+| **Framework** | Any (pure TS) | React Native only | Platform-locked |
+| **Runtime deps** | 0 | 50+ | N/A |
+| **Map renderer** | BYO (adapter) | Mapbox GL only | Google Maps only |
+| **Directions** | BYO (adapter) | Mapbox API only | Google API only |
+| **Off-route detection** | Built-in FSM | Basic | Basic |
+| **U-turn protection** | ✅ Bearing penalty | ❌ | ❌ |
+| **Parallel road resolver** | ✅ Built-in | ❌ | ❌ |
+| **Dead reckoning** | ✅ Built-in | ❌ | ❌ |
+| **Geofencing** | ✅ Built-in | ❌ | Paid API |
+| **ETA** | ✅ Offline | API only | API only |
+| **Voice triggers** | ✅ Built-in | SDK only | ❌ |
+| **Headless testing** | ✅ Full pipeline | ❌ | ❌ |
+| **Custom routes** | ✅ GPX/GeoJSON/Builder | ❌ | ❌ |
+| **License** | Core MIT / Pro commercial | Commercial | Commercial |
+
+---
+
+## Tier Model
+
+NavCore uses a two-tier model controlled by a signed license key:
+
+| Tier | Import | License | Includes |
+|---|---|---|---|
+| **Core** | `@ingissa/navcore-core/core` | MIT — free forever | Geo utils, Kalman filter, route snapping, directions adapters, route builder |
+| **Pro** | `@ingissa/navcore-core/pro` | Commercial key required | Dead reckoning, advanced bearing, deviation detection, FSMs, voice, ETA, geofencing |
+| **Engine** | `@ingissa/navcore-core` | Gated internally at runtime | Full `NavCore` orchestrator (license key unlocks Pro features) |
+
+---
+
+## Installation
+
+```bash
+npm install @ingissa/navcore-core
+```
+
+---
+
+## Quick Start
+
+### Core tier (no license needed)
+
+```typescript
+import { NavCore } from '@ingissa/navcore-core';
+import { OSRMDirectionsProvider } from '@ingissa/navcore-core/core';
+
+// 1. Get a route from your self-hosted OSRM (free)
+const provider = new OSRMDirectionsProvider({ baseUrl: 'http://router.project-osrm.org' });
+const route = await provider.getRoute([[2.3522, 48.8566], [2.3400, 48.8700]]);
+
+// 2. Create engine (Core features work without a key)
+const engine = new NavCore();
+engine.setRoute(route.geometry);
+engine.startNavigation();
+
+// 3. Feed GPS updates
+engine.on('arrival', () => console.log('Arrived!'));
+
+navigator.geolocation.watchPosition(({ coords }) => {
+  const state = engine.update({
+    coord: [coords.longitude, coords.latitude],
+    accuracy: coords.accuracy,
+    bearing: coords.heading,
+    speed: coords.speed ?? 0,
+    timestamp: Date.now(),
+  });
+
+  console.log('Distance remaining:', state.distanceToDestination, 'm');
+});
+```
+
+### Pro tier (with license key)
+
+```typescript
+import { NavCore } from '@ingissa/navcore-core';
+
+// Pro features unlock automatically with a valid key
+const engine = new NavCore({ licenseKey: 'your-signed-license-key' });
+engine.setRoute(routeCoords, instructions);
+engine.startNavigation();
+
+engine.on('instruction', (instr) => speak(instr.text));  // voice cues (PRO)
+engine.on('deviation', ({ anchorIndex }) => recalculate(anchorIndex));
+engine.on('arrival', () => console.log('Arrived!'));
+```
+
+### Using subpath imports directly
+
+```typescript
+// Free MIT tier
+import { KalmanFilter2D } from '@ingissa/navcore-core/core';
+import { OSRMDirectionsProvider } from '@ingissa/navcore-core/core';
+import { CustomRouteBuilder } from '@ingissa/navcore-core/core';
+
+// Commercial Pro tier
+import { DeadReckoningEngine } from '@ingissa/navcore-core/pro';
+import { VoiceTriggerEngine } from '@ingissa/navcore-core/pro';
+import { ETAEngine } from '@ingissa/navcore-core/pro';
+import { GeofencingEngine } from '@ingissa/navcore-core/pro';
+```
+
+---
+
+## Directions Providers (built-in, no extra install)
+
+```typescript
+import {
+  OSRMDirectionsProvider,        // Self-hosted OSRM (recommended, free)
+  ValhallaDirectionsProvider,    // Self-hosted Valhalla (free)
+  OpenRouteServiceProvider,      // openrouteservice.org (free tier)
+} from '@ingissa/navcore-core/core';
+
+// OSRM
+const osrm = new OSRMDirectionsProvider({ baseUrl: 'http://router.project-osrm.org' });
+const route = await osrm.getRoute([[lng1, lat1], [lng2, lat2]]);
+
+// Valhalla
+const valhalla = new ValhallaDirectionsProvider({ baseUrl: 'https://valhalla1.openstreetmap.de' });
+const route = await valhalla.getRoute([[lng1, lat1], [lng2, lat2]], { costing: 'auto' });
+```
+
+---
+
+## Renderer Adapters (separate packages)
+
+```bash
+npm install @ingissa/navcore-maplibre      # Web + MapLibre GL
+npm install @ingissa/navcore-leaflet       # Web + Leaflet.js
+npm install @ingissa/navcore-google-maps   # Google Maps JS API
+npm install @ingissa/navcore-mapbox        # React Native + @rnmapbox/maps
+npm install @ingissa/navcore-react-native  # React Native bindings
+npm install @ingissa/navcore-headless      # Node.js / CI testing
+```
+
+> ⚠️ Renderer adapter packages require a commercial license. [Get yours at navcore.dev/pricing](https://navcore.dev/pricing)
+
+---
+
+## Feature Reference
+
+### CORE — free, MIT
+
+| Feature | API |
+|---|---|
+| GPS smoothing | `KalmanFilter2D` |
+| Route snapping | `RouteSnapper` |
+| Haversine & bearing | `haversineDistance`, `getBearingBetweenPoints` |
+| Cumulative distances | `buildForwardCumulativeDistances` |
+| Route builder | `CustomRouteBuilder` |
+| Directions — OSRM | `OSRMDirectionsProvider` |
+| Directions — Valhalla | `ValhallaDirectionsProvider` |
+| Directions — ORS | `OpenRouteServiceProvider` |
+| Renderer interface | `MapRendererAdapter` |
+| License verification | `LicenseManager` |
+
+### PRO — commercial license required
+
+| Feature | API | FEATURES key |
+|---|---|---|
+| Advanced snapping (bearing + inertia) | `RouteSnapper` options | `ADVANCED_SNAPPING` |
+| Parallel road resolver | `ParallelRoadResolver` | `PARALLEL_ROAD_RESOLUTION` |
+| Dead reckoning | `DeadReckoningEngine` | `DEAD_RECKONING` |
+| Compound deviation detection | `DeviationDetector` | `COMPOUND_DEVIATION` |
+| Advanced bearing engine | `BearingEngine` | `ADVANCED_BEARING` |
+| Progress anti-regression | `ProgressTracker` | `PROGRESS_TRACKING` |
+| Route offset predictor | `RouteOffsetPredictor` | `ROUTE_OFFSET` |
+| Navigation lifecycle FSM | `NavigationFSM` | — |
+| Off-route FSM | `OffRouteFSM` | — |
+| Instruction editor | `InstructionEditor` | — |
+| Voice trigger engine | `VoiceTriggerEngine` | `VOICE_TRIGGERS` |
+| ETA engine (offline) | `ETAEngine` | `ETA` |
+| Geofencing engine | `GeofencingEngine` | `GEOFENCING` |
+
+---
+
+## License Gate Behaviour
+
+| Condition | Result |
+|---|---|
+| No `licenseKey` | Core features work; Pro features blocked with `console.warn` |
+| Valid Pro key | All features unlocked; `🔑 [NavCore] License validation complete. Plan: pro` logged |
+| `isDev: true` | All features bypassed (development mode) |
+| Expired / tampered key | Pro features blocked; status: `EXPIRED` / `INVALID` |
+
+License keys are verified **offline** using ECDSA P-256 — no network calls, no tracking.
+
+---
+
+## NavCore Engine API
+
+```typescript
+const engine = new NavCore(options?: NavCoreOptions);
+
+// Setup
+engine.setRoute(coords: Coordinate[], instructions?: NavInstruction[]);
+engine.startNavigation();
+
+// GPS update (returns state snapshot)
+const state: NavCoreState = engine.update(gpsUpdate: NavGpsUpdate);
+
+// Render tick (call at ~60fps between GPS updates)
+engine.tick(nowMs: number);
+
+// Events
+engine.on('instruction', (instr: NavInstruction) => void);
+engine.on('deviation',   ({ anchorIndex, ghostCoord }) => void);
+engine.on('arrival',     () => void);
+engine.on('routeLoaded', ({ routeLength }) => void);
+engine.off(event, handler);
+
+// State & introspection
+engine.getState(): NavCoreState;
+engine.getLicenseManager(): LicenseManager;
+engine.getRoute(): ReadonlyArray<Coordinate>;
+engine.destroy();
+```
+
+### NavCoreState
+
+```typescript
+interface NavCoreState {
+  snappedCoord: Coordinate | null;    // GPS-snapped position on route
+  rawGpsCoord: Coordinate | null;     // Raw GPS position
+  bearing: number;                    // Smoothed heading (degrees)
+  routeIndex: number;                 // Current segment index
+  distanceToRoute: number;            // Distance from route (metres)
+  corridor: number;                   // Dynamic off-route threshold (metres)
+  isOffRoute: boolean;                // True when deviation confirmed
+  hasArrived: boolean;
+  distanceToDestination: number | null;         // Remaining distance (metres)
+  distanceToNextInstruction: number | null;     // Distance to next turn
+  nextInstructionIndex: number | null;
+  currentSpeed: number;               // m/s
+  isGpsStale: boolean;
+  gpsAgeMs: number;
+  licenseStatus: string;              // 'VALID' | 'INVALID' | 'EXPIRED' | 'MISSING'
+}
+```
+
+---
+
+## Documentation
+
+| Guide | Link |
+|---|---|
+| Architecture | [docs/architecture.md](./docs/architecture.md) |
+| Getting Started | [docs/getting-started.md](./docs/getting-started.md) |
+| Directions Providers | [docs/directions-providers.md](./docs/directions-providers.md) |
+| Renderer Adapters | [docs/renderer-adapters.md](./docs/renderer-adapters.md) |
+| API Reference | [docs/api-reference.md](./docs/api-reference.md) |
+| Custom Routes | [docs/custom-routes.md](./docs/custom-routes.md) |
+| Instructions & Voice | [docs/instructions.md](./docs/instructions.md) |
+| Pro Features | [docs/p3-features.md](./docs/p3-features.md) |
+| Testing Guide | [docs/testing.md](./docs/testing.md) |
+
+---
+
+## License
+
+- **Core engine** (`@ingissa/navcore-core`): [MIT](./LICENSE) for open-source projects
+- **Pro features & adapters**: Commercial license required — [navcore.dev/pricing](https://navcore.dev/pricing)
+
+---
+
+© Ingissa · [navcore.dev](https://navcore.dev) · [contact@navcore.dev](mailto:contact@navcore.dev)

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@ingissa/navcore-core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "NavCore navigation engine — zero runtime dependencies. Framework-agnostic. Works in browsers, React Native, Node.js, and CI/CD.",
   "author": "Ingissa <contact@navcore.dev>",
   "license": "MIT",
   "homepage": "https://navcore.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ingissa/navcore-sdk"
+    "url": "git+https://github.com/ingissa/navcore-sdk.git"
   },
   "bugs": {
     "url": "https://github.com/ingissa/navcore-sdk/issues"