@spec drain_queue(map()) :: {list(), map()}

Drain the queue and return all events as a list.

Returns {events, updated_state} where the queue is now empty and flush_counter is incremented by the number of events.

@spec enqueue_event(map(), term()) :: {map(), boolean()}

Enqueue an event to the queue.

Returns {state, true} if accepted, {state, false} if queue is full. Increments the push_counter when an event is enqueued.

@spec maybe_request_flush(map()) :: map()

Check if flush should be requested based on queue size vs threshold.

@spec maybe_schedule_flush(map()) :: map()

Schedule the next flush timer.

@spec wait_until_drained(map(), timeout()) :: boolean()

Wait until push_counter == flush_counter or timeout.

Returns true if drained within timeout, false otherwise.