[SDK-568] Add stable cross-SDK identifiers to IterableDataRegion

[franco-zalamena-iterable]

📝 Summary

Add stable cross-SDK identifiers and lookup factories to IterableDataRegion, and log instead of silently falling back when a region is unrecognised.

🎟️ Jira Ticket: SDK-568

📖 Description

SDK-568 asks for a typed data region across the SDKs. Android already had it — IterableDataRegion has been a Java enum with US/EU since 3.6.0 (MOB-6309), IterableConfig defaults to US, and the builder setter is @NonNull-typed. The divergence the epic describes lives on iOS (config.dataRegion is a raw String, so a typo compiles and misroutes data) and Web (isEuIterableService boolean).

So this PR hardens Android into the shared reference shape rather than redesigning it. Everything is additive — no breaking change, and no action required from clients.

Deprecated

• IterableConstants.BASE_URL_API and BASE_URL_LINKS. Both are hardcoded to the US data region, are unused by the SDK (verified: zero references outside their own declarations), and contradict the configured IterableDataRegion. They still resolve to the same values, so nothing breaks. Named 3.12.0 as the removal version in both the javadoc and the CHANGELOG — assuming this ships in 3.11.0, that's one minor of runway. Deliberately named rather than left as "a future major": the last Android major was 3.0.0 (2018), while public API does get removed in minors (3.5.5 dropped setEncryptionEnforced, 3.8.0 dropped CBC encryption). An unnamed target is exactly how BASE_URL_API survived this long as dead public API. If 3.11.0 isn't the release this lands in, the named version needs adjusting to keep the window intact.

Reviewer notes

Not done deliberately: setDataRegion(String) / setDataRegion(int) builder overloads. Adding them would make an existing setDataRegion(null) call an ambiguous-overload compile error, since IterableDataRegion and String are unrelated reference types — source-breaking. The static from(...) factories give wrappers the same capability with no ambiguity.

getEndpoint() stays public. Narrowing it is the one breaking change available here and it isn't worth it.

Follow-up not in this PR: nothing in the repo will remind anyone to actually remove the constants at 3.12.0. That needs tracking in the 3.12.0 release scope, or it repeats the pattern it's meant to fix.

🧪 How to test?

How to test the changes added?

Unit tests: ./gradlew :iterableapi:testDebugUnitTest

New coverage in IterableDataRegionTest.kt (9 tests) — endpoints match the data centers, identifiers match the other SDKs, from() by region code / iOS-style endpoint URL / numeric code, case- and whitespace-insensitivity, unsupported-value fallback for both overloads, and identifier round-tripping. IterableConfigTest.kt adds nullDataRegionFallsBackToUs (via reflection, since the null is only reachable from Java).

Manual check of the logging path:

IterableConfig config = new IterableConfig.Builder()
    .setDataRegion(IterableDataRegion.from("eu-west-1"))  // unsupported
    .build();

Expect a warning tagged IterableDataRegion naming the supported values (US (0), EU (1)) and a fallback to US. Then confirm IterableDataRegion.from("EU") and from(1) both resolve to EU and that requests go to https://api.eu.iterable.com/api/.

📚 Docs PR if applicable

TODO — the new identifiers/factories and the 3.12.0 deprecation are customer-facing and should be documented before release.

[rtlsilva]

Minor grammatical nitpick: this javadoc documents the from() helpers, but doesn't mention that setDataRegion(null) itself falls back to US with a warning.
Since the parameter is non-null, this can be easy to miss on a quick read, and even more so when using plain Java which doesn't actually enforce this at compile-time.
Probably worth a sentence on the javadoc.

[rtlsilva]

IterableDataRegion.US.name() already returns "US" (and the same for EU), so this regionCode is an independently-maintained copy of the same string.

The newly-added javadoc for getCode() explains why code is deliberately decoupled from .ordinal() - is regionCode meant to be decoupled from .name() for a similar reason? If so, worth a line on the javadoc.