feat: Introduce public Polling API facade and internalize engine

[bosankus]

This commit refactors the PollingEngine by introducing a public PollingApi interface and a Polling facade object as the primary entry point for consumers. The PollingEngine itself is now internal, encapsulating the implementation details.

Key Changes:

• Public API Facade (Polling.kt, PollingApi.kt):
  • Introduced PollingApi interface defining the stable public contract for interacting with the polling functionality.
  • Created a Polling object that implements PollingApi and delegates calls to the internal PollingEngine. This is now the recommended way for apps to use the library.
  • PollingEngine.Handle is replaced by a public PollingSession data class, which is returned by Polling.startPolling and contains the session id.
• PollingEngine.kt Internalization:
  • PollingEngine object and its State enum are now internal.
  • Public methods on PollingEngine (e.g., startPolling, pollUntil, cancel, pause, resume, updateBackoff, cancelAll, shutdown, compose) are now internal or fun (if they were already part of the internal API). Consumers should use the Polling facade.
  • Removed metrics recording calls (recordAttempt, recordResult, recordComplete) from PollingEngine as the Metrics interface was removed.
• Configuration and Core (PollingConfig.kt, Core.kt):
  • Removed Logger and Metrics interfaces and their usage in PollingConfig and PollingConfigBuilder. Observability is now primarily through onAttempt, onResult, and onComplete hooks.
  • ErrorCodes object is now internal.
  • FetchStrategy, SuccessStrategy, RetryStrategy interfaces are now internal.
  • DefaultRetryPredicates object renamed to RetryPredicates and its retryOnNetworkServerTimeout predicate is renamed to networkOrServerOrTimeout.
  • The default throwableMapper in PollingConfig and PollingConfigBuilder now uses a stable public error code (-1) instead of the internal ErrorCodes.UNKNOWN_ERROR_CODE.
• Build & Documentation:
  • Updated group ID in pollingengine/build.gradle.kts from io.github.bosankus to in.androidplay.
  • Updated README:
    • Changed artifact coordinates to in.androidplay:pollingengine.
    • Updated usage examples to use the new Polling facade and RetryPredicates.
    • Added a section on "Control APIs and Runtime Updates" demonstrating Polling.startPolling, pause, resume, updateBackoff, cancel.
    • Added examples for RetryPredicates.
    • Added a note about the API rename (PollingEngineApi -> PollingApi, use Polling facade).
    • Removed "Pluggable logging and metrics" from the feature list.
  • Added docs/PollingEngine.md (renamed from composeApp/src/androidMain/kotlin/in/androidplay/pollingengine/Platform.android.kt which was an empty file): This new Markdown file serves as a developer guide, explaining the public API, concepts, and usage.
  • Updated docs/ci-setup.md with the new timestamp.
  • Updated gradle/libs.versions.toml:
    • pollingengine artifact path updated to in.androidplay:pollingengine.
    • kotlinx-coroutines version updated to 1.10.2.
• Sample App (App.kt):
  • Now uses the Polling facade instead of PollingEngine directly.
  • Uses Polling.run for one-shot polling instead of PollingEngine.startPolling with a job for simplified start/stop logic.
  • Removed PollingEngine.Handle and uses PollingSession (though direct handle usage is reduced due to Polling.run).
  • Pause/Resume functionality is now managed by a local isPaused state that controls the countdown timer, as Polling.run is synchronous. The actual engine pause/resume is not used in this simplified flow.
  • Stop functionality now cancels the pollingJob launched for Polling.run.
  • Added a retry strategy selector using RetryPredicates (Always, Never, Network/Server/Timeout).
  • Minor UI tweaks using AnimatedVisibility and RoundedCornerShape.
  • Round elapsed time values more consistently using kotlin.math.round.
• Testing (PollingEngineCoreTests.kt, PollingEngineCancellationTest.kt):
  • Added PollingEngineCoreTests.kt with basic tests for success, non-retryable failure, max attempts, overall timeout, and compose behavior.
  • Updated PollingEngineCancellationTest.kt to use Polling.run.
• Removed Files:
  • composeApp/src/commonMain/kotlin/in/androidplay/pollingengine/Greeting.kt
  • composeApp/src/commonMain/kotlin/in/androidplay/pollingengine/Platform.kt
  • composeApp/src/androidMain/kotlin/in/androidplay/pollingengine/Platform.android.kt (content moved to docs/PollingEngine.md)

Impact:

• Provides a clearer and more stable public API for library consumers via the Polling facade.
• Reduces the public API surface by internalizing engine details.
• Simplifies observability by focusing on callback hooks rather than pluggable interfaces for logging/metrics.
• The sample app demonstrates the new facade and provides a control to switch retry strategies.

[Copilot]

Pull Request Overview

This PR introduces a public polling API facade and internalizes the engine implementation to provide a cleaner, more stable public interface for consumers. The refactoring focuses on simplifying the API surface while maintaining backward compatibility for core functionality.

• Introduces Polling facade object as the primary entry point with PollingApi interface
• Internalizes PollingEngine and related implementation details
• Replaces Logger and Metrics interfaces with callback hooks for observability
• Updates package coordinates from io.github.bosankus to in.androidplay

Reviewed Changes

Copilot reviewed 24 out of 27 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
PollingEngineCoreTests.kt	New comprehensive test suite covering success, failure, timeout, and compose scenarios
PollingEngineCancellationTest.kt	Updated to use new Polling.run API
BackoffPolicyTest.kt	Reformatted test assertions for better readability
PollingConfigBuilder.kt	New builder class with comprehensive documentation and validation
PollingSession.kt	New lightweight session handle replacing internal Handle
PollingEngine.kt	Internalized with Flow-based API and improved pause/resume logic
PollingAPI.kt	New public interface defining stable API contract
Polling.kt	New facade object implementing PollingApi and delegating to internal engine
Core.kt	Internalized strategies and error codes, renamed DefaultRetryPredicates to RetryPredicates
App.kt	Updated sample app to use new facade with comprehensive ViewModel implementation

Comments suppressed due to low confidence (1)

pollingengine/src/commonMain/kotlin/in/androidplay/pollingengine/polling/PollingConfigBuilder.kt:1

• The hardcoded error code -1 is a magic number. Consider extracting this as a named constant to improve code maintainability and make the default behavior more explicit.

package `in`.androidplay.pollingengine.polling

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}