@stadiamaps/ferrostar 0.48.1 → 0.49.0

package/ferrostar.d.ts

@@ -1,46 +1,85 @@
 /* tslint:disable */
 /* eslint-disable */
 /**
- * The type of incident that has occurred.
+ * A geographic bounding box defined by its corners.
  */
-export type IncidentType = "accident" | "congestion" | "construction" | "disabled_vehicle" | "lane_restriction" | "mass_transit" | "miscellaneous" | "other_news" | "planned_event" | "road_closure" | "road_hazard" | "weather";
+export interface BoundingBox {
+    /**
+     * The southwest corner of the bounding box.
+     */
+    sw: GeographicCoordinate;
+    /**
+     * The northeast corner of the bounding box.
+     */
+    ne: GeographicCoordinate;
+}
 
 /**
- * Additional information to further specify a [`ManeuverType`].
+ * The lane type blocked by the incident.
  */
-export type ManeuverModifier = "uturn" | "sharp right" | "right" | "slight right" | "straight" | "slight left" | "left" | "sharp left";
+export type BlockedLane = "left" | "left center" | "left turn lane" | "center" | "right" | "right center" | "right turn lane" | "hov";
 
 /**
- * Information describing the series of steps needed to travel between two or more points.
+ * An instruction that can be synthesized using a TTS engine to announce an upcoming maneuver.
  *
- * NOTE: This type is unstable and is still under active development and should be
- * considered unstable.
+ * Note that these do not have any locale information attached.
  */
-export interface Route {
-    geometry: GeographicCoordinate[];
-    bbox: BoundingBox;
+export interface SpokenInstruction {
     /**
-     * The total route distance, in meters.
+     * Plain-text instruction which can be synthesized with a TTS engine.
      */
-    distance: number;
+    text: string;
     /**
-     * The ordered list of waypoints to visit, including the starting point.
-     * Note that this is distinct from the *geometry* which includes all points visited.
-     * A waypoint represents a start/end point for a route leg.
+     * Speech Synthesis Markup Language, which should be preferred by clients capable of understanding it.
      */
-    waypoints: Waypoint[];
-    steps: RouteStep[];
+    ssml: string | undefined;
+    /**
+     * How far (in meters) from the upcoming maneuver the instruction should start being spoken.
+     */
+    triggerDistanceBeforeManeuver: number;
+    /**
+     * A unique identifier for this instruction.
+     *
+     * This is provided so that platform-layer integrations can easily disambiguate between distinct utterances,
+     * which may have the same textual content.
+     * UUIDs conveniently fill this purpose.
+     *
+     * NOTE: While it is possible to deterministically create UUIDs, we do not do so at this time.
+     * This should be theoretically possible though if someone cares to write up a proposal and a PR.
+     */
+    utteranceId: string;
 }
 
 /**
- * The content of a visual instruction.
+ * Details about congestion for an incident.
  */
-export interface LaneInfo {
-    active: boolean;
-    directions: string[];
-    activeDirection: string | undefined;
+export interface Congestion {
+    /**
+     * The level of congestion caused by the incident.
+     *
+     * 0 = no congestion
+     *
+     * 100 = road closed
+     *
+     * Other values mean no congestion was calculated
+     */
+    value: number;
 }
 
+/**
+ * The type of incident that has occurred.
+ */
+export type IncidentType = "accident" | "congestion" | "construction" | "disabled_vehicle" | "lane_restriction" | "mass_transit" | "miscellaneous" | "other_news" | "planned_event" | "road_closure" | "road_hazard" | "weather";
+
+/**
+ * Which side of the road traffic drives on.
+ *
+ * This is needed by consumers like Android Auto to determine whether
+ * a roundabout should be rendered as clockwise (right-hand traffic)
+ * or counterclockwise (left-hand traffic).
+ */
+export type DrivingSide = "left" | "right";
+
 /**
  * A maneuver (such as a turn or merge) followed by travel of a certain distance until reaching
  * the next step.
@@ -104,47 +143,84 @@ export interface RouteStep {
 }
 
 /**
- * The location of the user that is navigating.
+ * Information describing the series of steps needed to travel between two or more points.
  *
- * In addition to coordinates, this includes estimated accuracy and course information,
- * which can influence navigation logic and UI.
+ * NOTE: This type is unstable and is still under active development and should be
+ * considered unstable.
+ */
+export interface Route {
+    geometry: GeographicCoordinate[];
+    bbox: BoundingBox;
+    /**
+     * The total route distance, in meters.
+     */
+    distance: number;
+    /**
+     * The ordered list of waypoints to visit, including the starting point.
+     * Note that this is distinct from the *geometry* which includes all points visited.
+     * A waypoint represents a start/end point for a route leg.
+     */
+    waypoints: Waypoint[];
+    steps: RouteStep[];
+}
+
+/**
+ * The broad class of maneuver to perform.
  *
- * NOTE: Heading is absent on purpose.
- * Heading updates are not related to a change in the user\'s location.
+ * This is usually combined with [`ManeuverModifier`] in [`VisualInstructionContent`].
  */
-export interface UserLocation {
-    coordinates: GeographicCoordinate;
+export type ManeuverType = "turn" | "new name" | "depart" | "arrive" | "merge" | "on ramp" | "off ramp" | "fork" | "end of road" | "continue" | "roundabout" | "rotary" | "roundabout turn" | "notification" | "exit roundabout" | "exit rotary";
+
+/**
+ * A geographic coordinate in WGS84.
+ */
+export interface GeographicCoordinate {
     /**
-     * The estimated accuracy of the coordinate (in meters)
+     * The latitude (in degrees).
      */
-    horizontalAccuracy: number;
-    courseOverGround: CourseOverGround | undefined;
-    timestamp: { secs_since_epoch: number; nanos_since_epoch: number };
-    speed: Speed | undefined;
+    lat: number;
+    /**
+     * The Longitude (in degrees).
+     */
+    lng: number;
 }
 
 /**
- * An instruction for visual display (usually as banners) at a specific point along a [`RouteStep`].
+ * The content of a visual instruction.
  */
-export interface VisualInstruction {
+export interface LaneInfo {
+    active: boolean;
+    directions: string[];
+    activeDirection: string | undefined;
+}
+
+/**
+ * The speed of the user from the location provider.
+ */
+export interface Speed {
     /**
-     * The primary instruction content.
-     *
-     * This is usually given more visual weight.
+     * The user\'s speed in meters per second.
      */
-    primaryContent: VisualInstructionContent;
+    value: number;
     /**
-     * Optional secondary instruction content.
+     * The accuracy of the speed value, measured in meters per second.
      */
-    secondaryContent: VisualInstructionContent | undefined;
+    accuracy: number | undefined;
+}
+
+/**
+ * The direction in which the user/device is observed to be traveling.
+ */
+export interface CourseOverGround {
     /**
-     * Optional sub-maneuver instruction content.
+     * The direction in which the user\'s device is traveling, measured in clockwise degrees from
+     * true north (N = 0, E = 90, S = 180, W = 270).
      */
-    subContent: VisualInstructionContent | undefined;
+    degrees: number;
     /**
-     * How far (in meters) from the upcoming maneuver the instruction should start being displayed
+     * The accuracy of the course value, measured in degrees.
      */
-    triggerDistanceBeforeManeuver: number;
+    accuracy: number | undefined;
 }
 
 /**
@@ -233,31 +309,57 @@ export interface Incident {
 }
 
 /**
- * A geographic bounding box defined by its corners.
+ * The impact of the incident that has occurred.
  */
-export interface BoundingBox {
+export type Impact = "unknown" | "critical" | "major" | "minor" | "low";
+
+/**
+ * An instruction for visual display (usually as banners) at a specific point along a [`RouteStep`].
+ */
+export interface VisualInstruction {
     /**
-     * The southwest corner of the bounding box.
+     * The primary instruction content.
+     *
+     * This is usually given more visual weight.
      */
-    sw: GeographicCoordinate;
+    primaryContent: VisualInstructionContent;
     /**
-     * The northeast corner of the bounding box.
+     * Optional secondary instruction content.
      */
-    ne: GeographicCoordinate;
+    secondaryContent: VisualInstructionContent | undefined;
+    /**
+     * Optional sub-maneuver instruction content.
+     */
+    subContent: VisualInstructionContent | undefined;
+    /**
+     * How far (in meters) from the upcoming maneuver the instruction should start being displayed
+     */
+    triggerDistanceBeforeManeuver: number;
 }
 
 /**
- * A geographic coordinate in WGS84.
+ * Additional information to further specify a [`ManeuverType`].
  */
-export interface GeographicCoordinate {
-    /**
-     * The latitude (in degrees).
-     */
-    lat: number;
+export type ManeuverModifier = "uturn" | "sharp right" | "right" | "slight right" | "straight" | "slight left" | "left" | "sharp left";
+
+/**
+ * The location of the user that is navigating.
+ *
+ * In addition to coordinates, this includes estimated accuracy and course information,
+ * which can influence navigation logic and UI.
+ *
+ * NOTE: Heading is absent on purpose.
+ * Heading updates are not related to a change in the user\'s location.
+ */
+export interface UserLocation {
+    coordinates: GeographicCoordinate;
     /**
-     * The Longitude (in degrees).
+     * The estimated accuracy of the coordinate (in meters)
      */
-    lng: number;
+    horizontalAccuracy: number;
+    courseOverGround: CourseOverGround | undefined;
+    timestamp: { secs_since_epoch: number; nanos_since_epoch: number };
+    speed: Speed | undefined;
 }
 
 /**
@@ -300,104 +402,6 @@ export interface Waypoint {
     properties: number[] | undefined;
 }
 
-/**
- * An instruction that can be synthesized using a TTS engine to announce an upcoming maneuver.
- *
- * Note that these do not have any locale information attached.
- */
-export interface SpokenInstruction {
-    /**
-     * Plain-text instruction which can be synthesized with a TTS engine.
-     */
-    text: string;
-    /**
-     * Speech Synthesis Markup Language, which should be preferred by clients capable of understanding it.
-     */
-    ssml: string | undefined;
-    /**
-     * How far (in meters) from the upcoming maneuver the instruction should start being spoken.
-     */
-    triggerDistanceBeforeManeuver: number;
-    /**
-     * A unique identifier for this instruction.
-     *
-     * This is provided so that platform-layer integrations can easily disambiguate between distinct utterances,
-     * which may have the same textual content.
-     * UUIDs conveniently fill this purpose.
-     *
-     * NOTE: While it is possible to deterministically create UUIDs, we do not do so at this time.
-     * This should be theoretically possible though if someone cares to write up a proposal and a PR.
-     */
-    utteranceId: string;
-}
-
-/**
- * The direction in which the user/device is observed to be traveling.
- */
-export interface CourseOverGround {
-    /**
-     * The direction in which the user\'s device is traveling, measured in clockwise degrees from
-     * true north (N = 0, E = 90, S = 180, W = 270).
-     */
-    degrees: number;
-    /**
-     * The accuracy of the course value, measured in degrees.
-     */
-    accuracy: number | undefined;
-}
-
-/**
- * The broad class of maneuver to perform.
- *
- * This is usually combined with [`ManeuverModifier`] in [`VisualInstructionContent`].
- */
-export type ManeuverType = "turn" | "new name" | "depart" | "arrive" | "merge" | "on ramp" | "off ramp" | "fork" | "end of road" | "continue" | "roundabout" | "rotary" | "roundabout turn" | "notification" | "exit roundabout" | "exit rotary";
-
-/**
- * The speed of the user from the location provider.
- */
-export interface Speed {
-    /**
-     * The user\'s speed in meters per second.
-     */
-    value: number;
-    /**
-     * The accuracy of the speed value, measured in meters per second.
-     */
-    accuracy: number | undefined;
-}
-
-/**
- * The impact of the incident that has occurred.
- */
-export type Impact = "unknown" | "critical" | "major" | "minor" | "low";
-
-/**
- * Details about congestion for an incident.
- */
-export interface Congestion {
-    /**
-     * The level of congestion caused by the incident.
-     *
-     * 0 = no congestion
-     *
-     * 100 = road closed
-     *
-     * Other values mean no congestion was calculated
-     */
-    value: number;
-}
-
-/**
- * The lane type blocked by the incident.
- */
-export type BlockedLane = "left" | "left center" | "left turn lane" | "center" | "right" | "right center" | "right turn lane" | "hov";
-
-/**
- * Describes characteristics of the waypoint for routing purposes.
- */
-export type WaypointKind = "Break" | "Via";
-
 /**
  * The content of a visual instruction.
  */
@@ -433,13 +437,9 @@ export interface VisualInstructionContent {
 }
 
 /**
- * Which side of the road traffic drives on.
- *
- * This is needed by consumers like Android Auto to determine whether
- * a roundabout should be rendered as clockwise (right-hand traffic)
- * or counterclockwise (left-hand traffic).
+ * Describes characteristics of the waypoint for routing purposes.
  */
-export type DrivingSide = "left" | "right";
+export type WaypointKind = "Break" | "Via";
 
 /**
  * Configurations for built-in route providers.
@@ -469,6 +469,8 @@ export interface NavigationRecordingEvent {
  */
 export type NavigationRecordingEventData = { StateUpdate: { trip_state: TripState; step_advance_condition: SerializableStepAdvanceCondition } } | { RouteUpdate: { route: Route } };
 
+export type SimulationError = { PolylineError: { error: string } } | "NotEnoughPoints";
+
 /**
  * Controls how simulated locations deviate from the actual route line.
  * This simulates real-world GPS behavior where readings often have systematic bias.
@@ -484,7 +486,16 @@ export interface LocationSimulationState {
     bias: LocationBias;
 }
 
-export type SimulationError = { PolylineError: { error: string } } | "NotEnoughPoints";
+/**
+ * Specifies a preferred side for departing from / arriving at a location.
+ *
+ * Examples:
+ * - Germany drives on the right side of the road. A value of `same` will only allow leaving
+ *   or arriving at a location such that it is on your right.
+ * - Australia drives on the left side of the road. Passing a value of `same` will only allow
+ *   leaving or arriving at a location such that it is on your left.
+ */
+export type ValhallaWaypointPreferredSide = "same" | "opposite" | "either";
 
 /**
  * A set of optional filters to exclude candidate edges based on their attributes.
@@ -643,17 +654,6 @@ export interface ValhallaWaypointProperties {
     allow_uturns: boolean | undefined;
 }
 
-/**
- * Specifies a preferred side for departing from / arriving at a location.
- *
- * Examples:
- * - Germany drives on the right side of the road. A value of `same` will only allow leaving
- *   or arriving at a location such that it is on your right.
- * - Australia drives on the left side of the road. Passing a value of `same` will only allow
- *   leaving or arriving at a location such that it is on your left.
- */
-export type ValhallaWaypointPreferredSide = "same" | "opposite" | "either";
-
 /**
  * Waypoint properties parsed from an OSRM-compatible server response.
  *
@@ -674,11 +674,6 @@ export interface OsrmWaypointProperties {
     distance: number | undefined;
 }
 
-/**
- * Determines if the user has deviated from the expected route.
- */
-export type RouteDeviationTracking = "None" | { StaticThreshold: { minimumHorizontalAccuracy: number; maxAcceptableDeviation: number } };
-
 /**
  * Status information that describes whether the user is proceeding according to the route or not.
  *
@@ -687,10 +682,45 @@ export type RouteDeviationTracking = "None" | { StaticThreshold: { minimumHorizo
  */
 export type RouteDeviation = "NoDeviation" | { OffRoute: { deviationFromRouteLine: number } };
 
+/**
+ * Determines if the user has deviated from the expected route.
+ */
+export type RouteDeviationTracking = "None" | { StaticThreshold: { minimumHorizontalAccuracy: number; maxAcceptableDeviation: number } };
+
 export type SerializableStepAdvanceCondition = "Manual" | { DistanceToEndOfStep: { distance: number; minimumHorizontalAccuracy: number } } | { DistanceFromStep: { distance: number; minimumHorizontalAccuracy: number; calculateWhileOffRoute: boolean } } | { DistanceEntryExit: { distanceToEndOfStep: number; distanceAfterEndStep: number; minimumHorizontalAccuracy: number; hasReachedEndOfCurrentStep: boolean } } | { DistanceEntryAndSnappedExit: { distanceToEndOfStep: number; distanceAfterEndStep: number; minimumHorizontalAccuracy: number; hasReachedEndOfCurrentStep: boolean } } | { OrAdvanceConditions: { conditions: SerializableStepAdvanceCondition[] } } | { AndAdvanceConditions: { conditions: SerializableStepAdvanceCondition[] } };
 
 export type GraphHopperVoiceUnits = "metric" | "imperial";
 
+export interface SerializableNavState {
+    tripState: TripState;
+    stepAdvanceCondition: SerializableStepAdvanceCondition;
+}
+
+/**
+ * Controls filtering/post-processing of user course by the [`NavigationController`].
+ */
+export type CourseFiltering = "SnapToRoute" | "Raw";
+
+/**
+ * High-level state describing progress through a route.
+ */
+export interface TripProgress {
+    /**
+     * The distance to the next maneuver, in meters.
+     */
+    distanceToNextManeuver: number;
+    /**
+     * The total distance remaining in the trip, in meters.
+     *
+     * This is the sum of the distance remaining in the current step and the distance remaining in all subsequent steps.
+     */
+    distanceRemaining: number;
+    /**
+     * The total duration remaining in the trip, in seconds.
+     */
+    durationRemaining: number;
+}
+
 /**
  * The state of a navigation session.
  *
@@ -700,6 +730,27 @@ export type GraphHopperVoiceUnits = "metric" | "imperial";
  */
 export type TripState = { Idle: { user_location: UserLocation | undefined } } | { Navigating: { currentStepGeometryIndex: number | undefined; userLocation: UserLocation; snappedUserLocation: UserLocation; remainingSteps: RouteStep[]; remainingWaypoints: Waypoint[]; progress: TripProgress; summary: TripSummary; deviation: RouteDeviation; visualInstruction: VisualInstruction | undefined; spokenInstruction: SpokenInstruction | undefined; annotationJson: string | undefined } } | { Complete: { user_location: UserLocation; summary: TripSummary } };
 
+/**
+ * Controls when a waypoint should be marked as complete.
+ *
+ * While a route may consist of thousands of points, waypoints are special.
+ * A simple trip will have only one waypoint: the final destination.
+ * A more complex trip may have several intermediate stops.
+ * Just as the navigation state keeps track of which steps remain in the route,
+ * it also tracks which waypoints are still remaining.
+ *
+ * Tracking waypoints enables Ferrostar to reroute users when they stray off the route line.
+ * The waypoint advance mode specifies how the framework decides
+ * that a waypoint has been visited (and is removed from the list).
+ *
+ * NOTE: Advancing to the next *step* and advancing to the next *waypoint*
+ * are separate processes.
+ * This will not normally cause any issues, but keep in mind that
+ * manually advancing to the next step does not *necessarily* imply
+ * that the waypoint will be marked as complete!
+ */
+export type WaypointAdvanceMode = { WaypointWithinRange: number } | { WaypointAlongAdvancingStep: number };
+
 /**
  * Information pertaining to the user\'s full navigation trip. This includes
  * simple stats like total duration and distance.
@@ -723,16 +774,6 @@ export interface TripSummary {
     endedAt: Date | null;
 }
 
-export interface SerializableNavState {
-    tripState: TripState;
-    stepAdvanceCondition: SerializableStepAdvanceCondition;
-}
-
-/**
- * Controls filtering/post-processing of user course by the [`NavigationController`].
- */
-export type CourseFiltering = "SnapToRoute" | "Raw";
-
 export interface SerializableNavigationControllerConfig {
     /**
      * Configures when navigation advances to the next waypoint in the route.
@@ -763,47 +804,6 @@ export interface SerializableNavigationControllerConfig {
     snappedLocationCourseFiltering: CourseFiltering;
 }
 
-/**
- * Controls when a waypoint should be marked as complete.
- *
- * While a route may consist of thousands of points, waypoints are special.
- * A simple trip will have only one waypoint: the final destination.
- * A more complex trip may have several intermediate stops.
- * Just as the navigation state keeps track of which steps remain in the route,
- * it also tracks which waypoints are still remaining.
- *
- * Tracking waypoints enables Ferrostar to reroute users when they stray off the route line.
- * The waypoint advance mode specifies how the framework decides
- * that a waypoint has been visited (and is removed from the list).
- *
- * NOTE: Advancing to the next *step* and advancing to the next *waypoint*
- * are separate processes.
- * This will not normally cause any issues, but keep in mind that
- * manually advancing to the next step does not *necessarily* imply
- * that the waypoint will be marked as complete!
- */
-export type WaypointAdvanceMode = { WaypointWithinRange: number } | { WaypointAlongAdvancingStep: number };
-
-/**
- * High-level state describing progress through a route.
- */
-export interface TripProgress {
-    /**
-     * The distance to the next maneuver, in meters.
-     */
-    distanceToNextManeuver: number;
-    /**
-     * The total distance remaining in the trip, in meters.
-     *
-     * This is the sum of the distance remaining in the current step and the distance remaining in all subsequent steps.
-     */
-    distanceRemaining: number;
-    /**
-     * The total duration remaining in the trip, in seconds.
-     */
-    durationRemaining: number;
-}
-
 
 export class NavigationController {
   free(): void;

package/package.json

@@ -7,7 +7,7 @@
     "Luke Seelenbinder <luke@stadiamaps.com>"
   ],
   "description": "The core of modern turn-by-turn navigation.",
-  "version": "0.48.1",
+  "version": "0.49.0",
   "license": "BSD-3-Clause",
   "repository": {
     "type": "git",