====================
Android Trip feature
====================

Our SDK can manage for you the notion of trip, giving you useful data like traveled distance or the start time of the user's last ongoing stop.

Get the SDK instance
====================

After initialization, use the shared instance to access trip APIs.

.. code-block:: kotlin

    // Initialize once (e.g., in Application.onCreate)
    val sdk = SafeRider.initialize(appContext, "<API_KEY>")

    // Later, anywhere in the app
    val safeRider = SafeRider.sharedInstance


Manage a trip
=============

Trip status
-----------

.. code-block:: kotlin

    // Public type exposed by the SDK
    sealed class LRTripStatus {
        data class Ongoing(
            val tripStartTime: Long,      // UTC epoch millis
            val distanceMeter: Double,    // meters since tripStartTime
            val dwellStartTime: Long?     // UTC epoch millis or null if moving
        ) : LRTripStatus()

        data object None : LRTripStatus()
    }

The ``LRTripStatus`` gives you useful data about an ongoing trip:

* ``tripStartTime``: UTC epoch milliseconds when the trip started.
* ``distanceMeter``: total traveled distance in meters since ``tripStartTime``.
* ``dwellStartTime``: UTC epoch milliseconds when the last dwell started, or ``null`` if the user is currently moving.

Start a trip
------------

Start a manual trip. If a trip is already running, the current status is returned.

.. code-block:: kotlin

    val status: SafeRider.LRTripStatus.Ongoing =
        SafeRider.sharedInstance.startTrip()

Stop a trip
-----------

Stop the current manual trip.

.. code-block:: kotlin

    SafeRider.sharedInstance.stopTrip()

Use Kotlin Flow (recommended)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collect ``tripStatusFlow`` to be notified of changes, and read ``tripStatus`` for an immediate snapshot.

.. code-block:: kotlin

    val sdk = SafeRider.sharedInstance

    // Snapshot
    val current: SafeRider.LRTripStatus = sdk.tripStatus

    // Reactive updates
    sdk.tripStatusFlow.collect { status ->
        when (status) {
            is SafeRider.LRTripStatus.Ongoing -> {
                // status.tripStartTime, status.distanceMeter, status.dwellStartTime
            }
            SafeRider.LRTripStatus.None -> {
                // No active trip
            }
        }
    }

Use a listener (Java/Kotlin)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Register a listener if you cannot use coroutines/Flow.

.. code-block:: kotlin

    val sdk = SafeRider.sharedInstance

    val listener = object : SafeRider.LRTripStatusListener {
        override fun onTripStatusChanged(tripStatus: SafeRider.LRTripStatus) {
            when (tripStatus) {
                is SafeRider.LRTripStatus.Ongoing -> {
                    // tripStatus.tripStartTime, tripStatus.distanceMeter, tripStatus.dwellStartTime
                }
                SafeRider.LRTripStatus.None -> { /* No trip */ }
            }
        }
    }

    sdk.addTripStatusListener(listener)
    // Later
    sdk.removeTripStatusListener(listener)

Notes
-----

* ``tripStatusFlow`` is a ``StateFlow``: the first emission is always the current state.
* Public APIs are intended to be called from the main thread.
* During a manual trip, automatic trip detection analysis is muted and is unmuted when the trip stops.
* There is no dedicated trip status error stream on Android; implement your own guards as needed.