[SDK-566] Accept fractional seconds for expiringAuthTokenRefreshPeriod

[franco-zalamena-iterable]

📝 Summary

Android now accepts fractional seconds for expiringAuthTokenRefreshPeriod, matching iOS/RN/Flutter, and validates the value instead of silently scheduling refreshes after expiry.

🎟️ Jira Ticket: SDK-566

📖 Description

Stacked on #1077 — base is feature/SDK-547-jwt-timer-race, not master. Both branches modify IterableAuthManager.java and the same CHANGELOG section, so stacking avoids a conflict. Merge #1077 first; this will auto-retarget to master.

⚠️ The ticket's premise is wrong — please read before reviewing

SDK-566 states that Android interprets expiringAuthTokenRefreshPeriod in milliseconds while the other SDKs use seconds, and asks for a breaking unit change plus a coordinated version bump.

Android already uses seconds. Verified against all four codebases:

Platform	Public API	Unit	Default
Android	Builder.setExpiringAuthTokenRefreshPeriod(...)	seconds (* 1000L internally)	60 s
iOS	config.expiringAuthTokenRefreshPeriod: TimeInterval	seconds	60 s
React Native	IterableConfig.expiringAuthTokenRefreshPeriod	seconds	60 s
Flutter	IterableConfig.expiringAuthTokenRefreshPeriod	seconds	60 s

The 60000L the ticket cites is the Builder's internal millisecond representation of 60 s, not a public seconds-valued default. The * 1000L conversion has been there since 2020 (090bff97f, 2cc5f9800).

Corroboration: the RN and Flutter bridges pass seconds straight into the Android setter. If the premise were true, every hybrid app would already have a 1000x bug.

So making the requested change would introduce the bug the ticket aims to prevent. It is deliberately not done here. No breaking change, no coordinated version bump.

What the real gap was

Android accepted whole seconds only (Long), while iOS/RN/Flutter accept fractional seconds. 0.5 was not expressible. That is a genuine parity gap, and it is what this PR fixes.

1. Fractional seconds (Added)
New setExpiringAuthTokenRefreshPeriod(double) overload. The Long overload is deprecated and delegates to it, so existing callers are unaffected — source and binary compatible. Overload resolution verified for 120L, a boxed Long, a bare int, and 0.5; none are ambiguous.

2. Input validation (Fixed) — two real bugs, both reproduced:

• Negative → -60 became -60000 ms, and the period is subtracted when computing the refresh time, so the refresh was scheduled 60 s after the token had already expired.
• Overflow → Long.MAX_VALUE * 1000L wraps to -1000, same past-expiry path.
• Null → NPE on unboxing the @NonNull Long.

Now logged and corrected in the SDK's existing log-and-continue style (throwing would be a new crash surface for an init-time setter): null/NaN/negative fall back to the 60 s default; values above ~10 years are clamped. Zero stays valid — it means "refresh once expired" — and is covered by a test so it isn't "fixed" later.

3. Internal naming (Changed)
The core confusion is that one name meant seconds publicly and milliseconds internally. Package-private carriers renamed to ...Millis (IterableConfig, IterableAuthManager, RetryPolicy). All final/package-private — invisible outside the SDK. Public setter names and parameters are untouched.

Follow-ups (not in this PR)

• React Native — the Android bridge reads the value with optLong, so 12.7 truncates to 12 while iOS keeps 12.7. Fix is committed on feature/SDK-566-rn-fractional-refresh-period but cannot compile until an iterableapi release carries the double overload — RN pins 3.6.2, which publishes only the Long overload (javac: double cannot be converted to Long). Sequenced after this ships.
• Flutter — unverified; Extensions.kt suggests it truncates the same way.

[rtlsilva]

LGTM