fix: address Cursor BugBot review findings on token-bucket governor

- Reword `flushDepth` doc comment to describe behavior without cross-repo
  reference (Android SDK mention removed per org policy)
- Add `resetFlushTokenBucket()` helper on KlaviyoState that restores
  availableFlushTokens to capacity and clears lastFlushTokenRefill
- Call `resetFlushTokenBucket()` on the company-switch path of `.initialize`
  so a depleted bucket from the previous API key cannot throttle flushes
  for the incoming company
- Add unit test `test_initialize_withNewApiKey_resetsBucketToFull` verifying
  the bucket is restored to full after switching API keys

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ajaysubra

Sources/KlaviyoSwift/StateManagement/KlaviyoState+FlushTokenBucket.swift

@@ -13,6 +13,15 @@
 import Foundation
 
 extension KlaviyoState {
+    /// Resets the token bucket to full capacity with no recorded refill timestamp,
+    /// reproducing the cold-launch state. Call this whenever a new API key is set so
+    /// the bucket from the previous company does not throttle the incoming company's
+    /// first flush cycle.
+    mutating func resetFlushTokenBucket() {
+        availableFlushTokens = StateManagementConstants.flushTokenBucketCapacity
+        lastFlushTokenRefill = nil
+    }
+
     /// `true` when the queue has grown large enough to warrant an early flush attempt
     /// rather than waiting for the next flush-interval tick. Suppressed when the
     /// `flushInterval` is non-finite (i.e. offline) so we don't kick off doomed requests.

Sources/KlaviyoSwift/StateManagement/StateManagement.swift

@@ -33,9 +33,9 @@ enum StateManagementConstants {
     static let flushTokenBucketCapacity = 5.0
 
     /// Queue depth that triggers an early flush attempt instead of waiting for the next
-    /// flush-interval tick. Mirrors the Android SDK's batch flush depth so the burst
-    /// behavior is consistent across platforms. The token bucket still gates whether the
-    /// early flush actually proceeds.
+    /// flush-interval tick. When the queue reaches this size the SDK schedules an immediate
+    /// flush to drain large bursts quickly; the token bucket still gates whether the flush
+    /// actually proceeds, so the long-term rate is preserved.
     static let flushDepth = 25
 }
 
@@ -199,6 +199,9 @@ struct KlaviyoReducer: ReducerProtocol {
                 }
                 state.apiKey = apiKey
                 state.reset()
+                // Restore the token bucket to full capacity so the incoming company's
+                // first flush is not throttled by activity from the previous company.
+                state.resetFlushTokenBucket()
             }
             guard case .uninitialized = state.initalizationState else {
                 return .none

Tests/KlaviyoSwiftTests/FlushTokenBucketTests.swift

@@ -147,4 +147,36 @@ final class FlushTokenBucketTests: XCTestCase {
         await store.send(.enqueueAggregateEvent(Data("agg".utf8)))
         await store.receive(.flushQueue)
     }
+
+    // MARK: - token bucket reset on company switch
+
+    /// Verifies that re-initializing with a *different* API key resets the token bucket to
+    /// full capacity, so a depleted bucket from the previous company cannot throttle the
+    /// incoming company's first flush cycle.
+    ///
+    /// When `.initialize` is dispatched against an already-initialized state with a new key,
+    /// the reducer resets profile data and restores the bucket, then returns `.none` (it
+    /// cannot transition to `.initializing` because `initalizationState` is no longer
+    /// `.uninitialized`). The state is verified synchronously via the `send` expectation
+    /// before any async work fires.
+    @MainActor
+    func test_initialize_withNewApiKey_resetsBucketToFull() async {
+        // Start with an already-initialized state whose bucket is fully depleted.
+        var initialState = INITIALIZED_TEST_STATE()
+        initialState.availableFlushTokens = 0
+        initialState.lastFlushTokenRefill = environment.date()
+
+        let store = TestStore(initialState: initialState, reducer: KlaviyoReducer())
+        store.exhaustivity = .off
+
+        let newApiKey = "new-company-key"
+        await store.send(.initialize(newApiKey)) {
+            // The bucket must be restored to full capacity on a company switch.
+            $0.availableFlushTokens = StateManagementConstants.flushTokenBucketCapacity
+            $0.lastFlushTokenRefill = nil
+            $0.apiKey = newApiKey
+            // initalizationState stays .initialized — the guard in .initialize exits early
+            // because the state is not .uninitialized after the company-switch branch runs.
+        }
+    }
 }