@doorstepai/dropoff-sdk 2.0.2 → 2.0.5

package/android/build.gradle

@@ -86,7 +86,7 @@ def kotlin_version = getExtOrDefault("kotlinVersion")
 dependencies {
   implementation "com.facebook.react:react-android"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
-  implementation("ai.doorstep.com:doorstepai-dropoff-sdk:2.0.1")
+  implementation("ai.doorstep.com:doorstepai-dropoff-sdk:2.0.6")
   api "org.jetbrains.kotlinx:kotlinx-serialization-json:1.5.1"
 }
 

package/android/src/main/java/com/doorstepai/dropoffsdk/DoorstepAIModule.kt

@@ -9,6 +9,7 @@ import com.facebook.react.bridge.Promise
 import com.doorstepai.sdks.tracking.DoorstepAI
 import com.doorstepai.sdks.tracking.AddressType
 import com.doorstepai.sdks.tracking.DropoffType
+import com.doorstepai.sdks.tracking.LatLngObject
 import com.facebook.react.bridge.ReadableMap
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.CoroutineScope
@@ -42,10 +43,18 @@ class DoorstepAIModule(private val reactContext: ReactApplicationContext) :
     placeID: String,
     deliveryId: String,
     timeoutSeconds: Double?,
+    autoStopAfterDropoffSeconds: Double?,
+    manualForeground: Boolean?,
     promise: Promise
   ) {
     try {
-      DoorstepAI.startDeliveryByPlaceID(placeID, deliveryId, timeoutSeconds) { result ->
+      DoorstepAI.startDeliveryByPlaceID(
+        placeID = placeID,
+        deliveryId = deliveryId,
+        timeoutSeconds = timeoutSeconds,
+        manualForeground = manualForeground ?: false,
+        autoStopAfterDropoffSeconds = autoStopAfterDropoffSeconds
+      ) { result ->
         result.onSuccess { sessionId ->
           promise.resolve(sessionId)
         }.onFailure { error ->
@@ -81,11 +90,22 @@ class DoorstepAIModule(private val reactContext: ReactApplicationContext) :
   fun startDeliveryByAddressString(
     address: String,
     deliveryId: String,
+    coordinates: ReadableMap?,
     timeoutSeconds: Double?,
+    autoStopAfterDropoffSeconds: Double?,
+    manualForeground: Boolean?,
     promise: Promise
   ) {
     try {
-      DoorstepAI.startDeliveryByAddressString(address, deliveryId, timeoutSeconds) { result ->
+      val coords = parseCoordinates(coordinates)
+      DoorstepAI.startDeliveryByAddressString(
+        address = address,
+        deliveryId = deliveryId,
+        coordinates = coords,
+        timeoutSeconds = timeoutSeconds,
+        manualForeground = manualForeground ?: false,
+        autoStopAfterDropoffSeconds = autoStopAfterDropoffSeconds
+      ) { result ->
         result.onSuccess { message ->
           promise.resolve(message)
         }.onFailure { error ->
@@ -123,7 +143,10 @@ class DoorstepAIModule(private val reactContext: ReactApplicationContext) :
   fun startDeliveryByAddress(
     addressMap: ReadableMap,
     deliveryId: String,
+    coordinates: ReadableMap?,
     timeoutSeconds: Double?,
+    autoStopAfterDropoffSeconds: Double?,
+    manualForeground: Boolean?,
     promise: Promise
   ) {
     try {
@@ -143,7 +166,15 @@ class DoorstepAIModule(private val reactContext: ReactApplicationContext) :
         postalCode = postalCode
       )
 
-      DoorstepAI.startDeliveryByAddressType(address, deliveryId, timeoutSeconds) { result ->
+      val coords = parseCoordinates(coordinates)
+      DoorstepAI.startDeliveryByAddressType(
+        address = address,
+        deliveryId = deliveryId,
+        coordinates = coords,
+        timeoutSeconds = timeoutSeconds,
+        manualForeground = manualForeground ?: false,
+        autoStopAfterDropoffSeconds = autoStopAfterDropoffSeconds
+      ) { result ->
         result.onSuccess { sessionId ->
           promise.resolve(sessionId)
         }.onFailure { error ->
@@ -196,8 +227,9 @@ class DoorstepAIModule(private val reactContext: ReactApplicationContext) :
   }
 
   @ReactMethod(isBlockingSynchronousMethod = true)
-  fun setApiKey(key: String) {
+  fun setApiKey(key: String): Boolean {
     DoorstepAI.setAPIKey(key)
+    return true
   }
 
   @ReactMethod
@@ -224,60 +256,6 @@ class DoorstepAIModule(private val reactContext: ReactApplicationContext) :
     }
   }
 
-  @ReactMethod
-  fun hasCachedData(promise: Promise) {
-    CoroutineScope(Dispatchers.IO).launch {
-      try {
-        val result = DoorstepAI.hasCachedData()
-        promise.resolve(result)
-      } catch (e: Exception) {
-        promise.reject("HAS_CACHED_DATA_ERROR", e.message ?: "Failed to check cached data")
-      }
-    }
-  }
-
-  @ReactMethod
-  fun waitForCachedDataCompletion(promise: Promise) {
-    CoroutineScope(Dispatchers.IO).launch {
-      try {
-        val result = DoorstepAI.waitForCachedDataCompletion()
-        promise.resolve(result)
-      } catch (e: Exception) {
-        promise.reject("WAIT_CACHED_DATA_ERROR", e.message ?: "Failed while waiting for cached data completion")
-      }
-    }
-  }
-
-  @ReactMethod
-  fun isCacheProcessingInProgress(promise: Promise) {
-    try {
-      val result = DoorstepAI.isCacheProcessingInProgress()
-      promise.resolve(result)
-    } catch (e: Exception) {
-      promise.reject("CACHE_PROCESSING_STATUS_ERROR", e.message ?: "Failed to check cache processing status")
-    }
-  }
-
-  @ReactMethod
-  fun hasPendingNetworkRequests(promise: Promise) {
-    try {
-      val result = DoorstepAI.hasPendingNetworkRequests()
-      promise.resolve(result)
-    } catch (e: Exception) {
-      promise.reject("PENDING_NETWORK_REQUESTS_ERROR", e.message ?: "Failed to check pending network requests")
-    }
-  }
-
-  @ReactMethod
-  fun getPendingNetworkRequestsCount(promise: Promise) {
-    try {
-      val result = DoorstepAI.getPendingNetworkRequestsCount()
-      promise.resolve(result)
-    } catch (e: Exception) {
-      promise.reject("PENDING_NETWORK_REQUESTS_COUNT_ERROR", e.message ?: "Failed to get pending network requests count")
-    }
-  }
-
   @ReactMethod
   fun disableDevMode(promise: Promise) {
     try {
@@ -288,6 +266,13 @@ class DoorstepAIModule(private val reactContext: ReactApplicationContext) :
     }
   }
 
+  private fun parseCoordinates(map: ReadableMap?): LatLngObject? {
+    if (map == null) return null
+    val lat = if (map.hasKey("lat")) map.getDouble("lat") else return null
+    val lng = if (map.hasKey("lng")) map.getDouble("lng") else return null
+    return LatLngObject(lat = lat, lng = lng)
+  }
+
   companion object {
     const val NAME = "DoorstepAI"
   }

package/ios/DoorstepAI.mm

@@ -3,27 +3,39 @@
 @interface RCT_EXTERN_MODULE(DoorstepAI, NSObject)
 
 RCT_EXTERN_METHOD(setApiKey:(nonnull NSString *)apiKey)
+RCT_EXTERN_METHOD(requestAllPermissions:(BOOL)requestAlwaysLocation)
+RCT_EXTERN_METHOD(configureRemoteLogging:(BOOL)enabled
+                 minLevel:(nullable NSNumber *)minLevel
+                 flushIntervalSeconds:(nullable NSNumber *)flushIntervalSeconds
+                 batchSize:(nullable NSNumber *)batchSize
+                 maxQueueSize:(nullable NSNumber *)maxQueueSize)
 RCT_EXTERN_METHOD(enableDevMode:(nonnull NSString *)apiKey
                  resolver:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
 RCT_EXTERN_METHOD(startDeliveryByPlaceID:(nonnull NSString *)placeID
                  deliveryId:(nonnull NSString *)deliveryId
                  timeoutSeconds:(nullable NSNumber *)timeoutSeconds
+                 autoStopAfterDropoffSeconds:(nullable NSNumber *)autoStopAfterDropoffSeconds
                  resolver:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
 RCT_EXTERN_METHOD(startDeliveryByPlusCode:(nonnull NSString *)plusCode
                  deliveryId:(nonnull NSString *)deliveryId
                  timeoutSeconds:(nullable NSNumber *)timeoutSeconds
+                 autoStopAfterDropoffSeconds:(nullable NSNumber *)autoStopAfterDropoffSeconds
                  resolver:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
 RCT_EXTERN_METHOD(startDeliveryByAddress:(nonnull NSDictionary *)address
                  deliveryId:(nonnull NSString *)deliveryId
+                 coordinates:(nullable NSDictionary *)coordinates
                  timeoutSeconds:(nullable NSNumber *)timeoutSeconds
+                 autoStopAfterDropoffSeconds:(nullable NSNumber *)autoStopAfterDropoffSeconds
                  resolver:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
 RCT_EXTERN_METHOD(startDeliveryByAddressString:(nonnull NSString *)address
                  deliveryId:(nonnull NSString *)deliveryId
+                 coordinates:(nullable NSDictionary *)coordinates
                  timeoutSeconds:(nullable NSNumber *)timeoutSeconds
+                 autoStopAfterDropoffSeconds:(nullable NSNumber *)autoStopAfterDropoffSeconds
                  resolver:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
 RCT_EXTERN_METHOD(startDeliveryByLatLng:(nonnull NSNumber *)latitude
@@ -31,6 +43,7 @@ RCT_EXTERN_METHOD(startDeliveryByLatLng:(nonnull NSNumber *)latitude
                  subUnit:(nonnull NSString *)subUnit
                  deliveryId:(nonnull NSString *)deliveryId
                  timeoutSeconds:(nullable NSNumber *)timeoutSeconds
+                 autoStopAfterDropoffSeconds:(nullable NSNumber *)autoStopAfterDropoffSeconds
                  resolver:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
 RCT_EXTERN_METHOD(newEvent:(nonnull NSString *)eventName
@@ -44,9 +57,5 @@ RCT_EXTERN_METHOD(markDropoff:(nonnull NSString *)deliveryId
 RCT_EXTERN_METHOD(stopDelivery:(nonnull NSString *)deliveryId
                  resolver:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
-RCT_EXTERN_METHOD(hasCachedData:(RCTPromiseResolveBlock)resolve
-                 rejecter:(RCTPromiseRejectBlock)reject)
-RCT_EXTERN_METHOD(waitForCacheDataCompletion:(RCTPromiseResolveBlock)resolve
-                 rejecter:(RCTPromiseRejectBlock)reject)
 
-@end 
+@end

package/ios/DoorstepAI.swift

@@ -24,20 +24,44 @@ class DoorstepAIBridge: NSObject {
         DoorstepAI.setApiKey(key: apiKey)
     }
 
+    @objc
+    func requestAllPermissions(_ requestAlwaysLocation: Bool) {
+        DoorstepAI.requestAllPermissions(requestAlwaysLocation: requestAlwaysLocation)
+    }
+
+    @objc
+    func configureRemoteLogging(_ enabled: Bool,
+                                minLevel: NSNumber?,
+                                flushIntervalSeconds: NSNumber?,
+                                batchSize: NSNumber?,
+                                maxQueueSize: NSNumber?) {
+        let level = minLevel.flatMap { SDKLogLevel(rawValue: $0.intValue) } ?? .warning
+        DoorstepAI.configureRemoteLogging(
+            enabled: enabled,
+            minLevel: level,
+            flushInterval: flushIntervalSeconds?.doubleValue ?? 30,
+            batchSize: batchSize?.intValue ?? 50,
+            maxQueueSize: maxQueueSize?.intValue ?? 1000
+        )
+    }
+
     @objc
     func startDeliveryByPlaceID(_ placeID: NSString,
                                 deliveryId: NSString,
                                 timeoutSeconds: NSNumber?,
+                                autoStopAfterDropoffSeconds: NSNumber?,
                                 resolver resolve: @escaping RCTPromiseResolveBlock,
                                 rejecter reject: @escaping RCTPromiseRejectBlock) {
         // Use Swift's concurrency support to call the async method.
         Task {
             do {
                 let timeout = timeoutSeconds?.doubleValue
+                let autoStop = autoStopAfterDropoffSeconds?.doubleValue
                 try await DoorstepAI.startDeliveryByPlaceID(
                     placeID: placeID as String,
                     deliveryId: deliveryId as String,
-                    timeoutSeconds: timeout
+                    timeoutSeconds: timeout,
+                    autoStopAfterDropoffSeconds: autoStop
                 )
                 resolve(nil)
             } catch {
@@ -50,15 +74,18 @@ class DoorstepAIBridge: NSObject {
     func startDeliveryByPlusCode(_ plusCode: NSString,
                                  deliveryId: NSString,
                                  timeoutSeconds: NSNumber?,
+                                 autoStopAfterDropoffSeconds: NSNumber?,
                                  resolver resolve: @escaping RCTPromiseResolveBlock,
                                  rejecter reject: @escaping RCTPromiseRejectBlock) {
         Task {
             do {
                 let timeout = timeoutSeconds?.doubleValue
+                let autoStop = autoStopAfterDropoffSeconds?.doubleValue
                 try await DoorstepAI.startDeliveryByPlusCode(
                     plusCode: plusCode as String,
                     deliveryId: deliveryId as String,
-                    timeoutSeconds: timeout
+                    timeoutSeconds: timeout,
+                    autoStopAfterDropoffSeconds: autoStop
                 )
                 resolve(nil)
             } catch {
@@ -70,16 +97,22 @@ class DoorstepAIBridge: NSObject {
     @objc
     func startDeliveryByAddressString(_ address: NSString,
                                       deliveryId: NSString,
+                                      coordinates: NSDictionary?,
                                       timeoutSeconds: NSNumber?,
+                                      autoStopAfterDropoffSeconds: NSNumber?,
                                       resolver resolve: @escaping RCTPromiseResolveBlock,
                                       rejecter reject: @escaping RCTPromiseRejectBlock) {
         Task {
             do {
                 let timeout = timeoutSeconds?.doubleValue
+                let autoStop = autoStopAfterDropoffSeconds?.doubleValue
+                let coords = parseCoordinates(coordinates)
                 try await DoorstepAI.startDeliveryByAddressString(
                     address: address as String,
                     deliveryId: deliveryId as String,
-                    timeoutSeconds: timeout
+                    coordinates: coords,
+                    timeoutSeconds: timeout,
+                    autoStopAfterDropoffSeconds: autoStop
                 )
                 resolve(nil)
             } catch {
@@ -94,17 +127,20 @@ class DoorstepAIBridge: NSObject {
                                subUnit: NSString,
                                deliveryId: NSString,
                                timeoutSeconds: NSNumber?,
+                               autoStopAfterDropoffSeconds: NSNumber?,
                                resolver resolve: @escaping RCTPromiseResolveBlock,
                                rejecter reject: @escaping RCTPromiseRejectBlock) {
         Task {
             do {
                 let timeout = timeoutSeconds?.doubleValue
+                let autoStop = autoStopAfterDropoffSeconds?.doubleValue
                 try await DoorstepAI.startDeliveryByLatLng(
                     latitude: latitude.doubleValue,
                     longitude: longitude.doubleValue,
                     subUnit: subUnit as String,
                     deliveryId: deliveryId as String,
-                    timeoutSeconds: timeout
+                    timeoutSeconds: timeout,
+                    autoStopAfterDropoffSeconds: autoStop
                 )
                 resolve(nil)
             } catch {
@@ -116,11 +152,12 @@ class DoorstepAIBridge: NSObject {
     @objc
     func startDeliveryByAddress(_ address: [String: Any],
                                 deliveryId: NSString,
+                                coordinates: NSDictionary?,
                                 timeoutSeconds: NSNumber?,
+                                autoStopAfterDropoffSeconds: NSNumber?,
                                 resolver resolve: @escaping RCTPromiseResolveBlock,
                                 rejecter reject: @escaping RCTPromiseRejectBlock) {
         Task {
-            print("Starting delivery by address: \(address)")
             do {
                 guard let streetNumber = address["streetNumber"] as? String,
                       let route = address["route"] as? String,
@@ -140,10 +177,14 @@ class DoorstepAIBridge: NSObject {
                                             postalCode: postalCode)
 
                 let timeout = timeoutSeconds?.doubleValue
+                let autoStop = autoStopAfterDropoffSeconds?.doubleValue
+                let coords = parseCoordinates(coordinates)
                 try await DoorstepAI.startDeliveryByAddressType(
                     address: addressStruct,
                     deliveryId: deliveryId as String,
-                    timeoutSeconds: timeout
+                    coordinates: coords,
+                    timeoutSeconds: timeout,
+                    autoStopAfterDropoffSeconds: autoStop
                 )
                 resolve(nil)
             } catch let error as DoorstepAIError {
@@ -206,19 +247,13 @@ class DoorstepAIBridge: NSObject {
         }
     }
 
-    @objc
-    func hasCachedData(_ resolve: @escaping RCTPromiseResolveBlock,
-                       rejecter reject: @escaping RCTPromiseRejectBlock) {
-        resolve(DoorstepAI.hasCachedData())
-    }
-
-    @objc
-    func waitForCacheDataCompletion(_ resolve: @escaping RCTPromiseResolveBlock,
-                                    rejecter reject: @escaping RCTPromiseRejectBlock) {
-        Task {
-            let result = await DoorstepAI.waitForCacheDataCompletion()
-            resolve(result)
+    private func parseCoordinates(_ raw: NSDictionary?) -> LatLngObject? {
+        guard let coordinates = raw as? [String: Any],
+              let lat = coordinates["lat"] as? Double,
+              let lng = coordinates["lng"] as? Double else {
+            return nil
         }
+        return LatLngObject(lat: lat, lng: lng)
     }
 
 }

package/ios/DoorstepDropoffSDK.xcframework/Info.plist

@@ -10,15 +10,18 @@
 			<key>DebugSymbolsPath</key>
 			<string>dSYMs</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64</string>
+			<string>ios-arm64_x86_64-simulator</string>
 			<key>LibraryPath</key>
 			<string>DoorstepDropoffSDK.framework</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
+				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
 		</dict>
 		<dict>
 			<key>BinaryPath</key>
@@ -26,18 +29,15 @@
 			<key>DebugSymbolsPath</key>
 			<string>dSYMs</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64_x86_64-simulator</string>
+			<string>ios-arm64</string>
 			<key>LibraryPath</key>
 			<string>DoorstepDropoffSDK.framework</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
-				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
-			<key>SupportedPlatformVariant</key>
-			<string>simulator</string>
 		</dict>
 	</array>
 	<key>CFBundlePackageType</key>

package/ios/DoorstepDropoffSDK.xcframework/ios-arm64/DoorstepDropoffSDK.framework/Headers/DoorstepDropoffSDK.h

@@ -14,5 +14,6 @@ FOUNDATION_EXPORT double DoorstepDropoffSDKVersionNumber;
 FOUNDATION_EXPORT const unsigned char DoorstepDropoffSDKVersionString[];
 
 // In this header, you should import all the public headers of your framework using statements like #import <DoorstepDropoffSDK/PublicHeader.h>
+#import <DoorstepDropoffSDK/RateReducer.h>
 
 

package/ios/DoorstepDropoffSDK.xcframework/ios-arm64/DoorstepDropoffSDK.framework/Headers/RateReducer.h

@@ -0,0 +1,117 @@
+/**
+ * @file RateReducer.h
+ *
+ * Pure-C IMU rate reducer — port of the strapdown coning/sculling algorithm
+ * in the legacy C++ RateReducer.  Designed for integration into the
+ * DoorstepDropoffSDK sensor pipeline via SensorRateReducer.swift.
+ *
+ * Channel treatment:
+ *   - rotationRate / rawGyro    → coning-corrected integration (delta-angle)
+ *   - accel / userAccel         → sculling-corrected integration (delta-velocity)
+ *   - gravity / roll,pitch,yaw  → simple per-sample average over the epoch
+ *   - mag / heading / proximity → latest-value pass-through
+ *
+ * NOT compiled into the Xcode target by default; add RateReducer.c to the
+ * framework target if you want to call these functions from Objective-C.
+ * The active Swift implementation in SensorRateReducer.swift mirrors this
+ * code exactly and requires no project-file changes.
+ */
+
+#pragma once
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct { double x, y, z; } rr_vec3_t;
+
+/** Flat sample type — mirrors the fields of InternalSensorData. */
+typedef struct {
+    /* Inertial channels (coning/sculling-integrated, then rate-recovered) */
+    double rotation_rate_x, rotation_rate_y, rotation_rate_z;
+    double accel_x,         accel_y,         accel_z;
+    double raw_gyro_x,      raw_gyro_y,      raw_gyro_z;
+    double user_accel_x,    user_accel_y,    user_accel_z;
+
+    /* Averaged over the epoch */
+    double gravity_x, gravity_y, gravity_z;
+    double roll, pitch, yaw;
+
+    /* Latest-value pass-through */
+    double mag_x,     mag_y,     mag_z;
+    int    mag_accuracy;
+    double raw_mag_x, raw_mag_y, raw_mag_z;
+    double heading;
+    int    proximity_state;  /* 0 = false, 1 = true */
+
+    /* Timing */
+    double timestamp;    /* wall-clock timestamp of the epoch's last sample */
+    double delta_time;   /* total epoch duration in seconds */
+} rr_sample_t;
+
+/** Per-pair integration state for one (gyro, accel) channel pair. */
+typedef struct {
+    rr_vec3_t sum_delta_theta;   /* accumulated angular increments */
+    rr_vec3_t prev_delta_theta;  /* last sample's delta — NOT reset across epochs */
+    rr_vec3_t coning;            /* coning correction accumulator */
+
+    rr_vec3_t sum_delta_vel;     /* accumulated velocity increments */
+    rr_vec3_t prev_delta_vel;    /* last sample's delta — NOT reset across epochs */
+    rr_vec3_t sculling;          /* sculling correction accumulator */
+} rr_pair_state_t;
+
+/** Top-level rate-reducer state. Zero-initialise before calling rr_init(). */
+typedef struct {
+    rr_pair_state_t primary;  /* fusion gyro (rotationRate) + fusion accel */
+    rr_pair_state_t raw;      /* raw gyro + raw accel (includes gravity) */
+
+    rr_vec3_t sum_gravity;
+    double    sum_roll, sum_pitch, sum_yaw;
+
+    rr_sample_t latest;          /* latest-value fields, refreshed every sample */
+
+    double sum_delta_time;
+    double prev_timestamp;       /* 0.0 = not yet seen a sample */
+    double nominal_input_dt;     /* 1/inputHz — fallback when timestamps are missing */
+    int    count;                /* samples accumulated in the current epoch */
+    int    n;                    /* target samples per output epoch */
+
+    bool        output_ready;
+    rr_sample_t output;
+} rr_state_t;
+
+/**
+ * Initialise the rate reducer.
+ *
+ * @param rr        Pointer to a zero-initialised rr_state_t.
+ * @param input_hz  Sensor input rate (e.g. 100.0).
+ * @param output_hz Desired output rate (e.g. 50.0).
+ *                  n = round(input_hz / output_hz), clamped to [2, 100].
+ */
+void rr_init(rr_state_t *rr, double input_hz, double output_hz);
+
+/**
+ * Feed one input sample.
+ *
+ * @return true when an output sample is ready; retrieve it with rr_get_output().
+ */
+bool rr_process(rr_state_t *rr, const rr_sample_t *sample);
+
+/**
+ * Retrieve the pending output sample.
+ *
+ * @return true if a sample was available; false if rr_process() has not yet
+ *         returned true since the last retrieval.
+ */
+bool rr_get_output(rr_state_t *rr, rr_sample_t *out);
+
+/**
+ * Change the decimation factor at runtime.
+ * Epoch-in-progress is discarded; prev_delta_* state is preserved for continuity.
+ */
+void rr_set_n(rr_state_t *rr, int n);
+
+#ifdef __cplusplus
+}
+#endif