refactor(sdk)!: make DatahubClient the only way in

[JosteinGj]

Why

The SDK is about to be published to Maven Central for the first time. Once it is, every public type and constructor becomes API we cannot remove without a breaking release.

The intended shape is that DatahubClient is the one way in and everything else is reached through it. But almost all of the plumbing was public:

• ApiHttp and TokenProvider;
• the ingestors, BatchExecutor's callers, both disk spools and SeriesResolver;
• every *Service constructor, each taking the internal ApiHttp;
• SubscriptionListener.connect(httpClient, baseUrl, token, mapper, ...).

A caller could build a service around their own HTTP plumbing, and we would have had to keep those constructors stable forever. Narrowing them after publication is a breaking change, so it has to happen before 0.3.0.

What changes

Java can only hide a constructor from other packages. So the services, BinaryIngestBuffer, SubscriptionListener and all the plumbing move into ai.intellistream.datahub.sdk.client beside DatahubClient, where they can be package-private:

• package-private classes: ApiHttp, TokenProvider, DatapointIngestor, EventIngestor, BinaryDatapointIngestor, DatapointSpool, DurableSpool, SeriesResolver (BatchExecutor and VaultSecretLoader already were);
• public classes with package-private constructors: every *Service and BinaryIngestBuffer. You get them from client.timeseries(), binaryBuffer() and so on;
• package-private factory: SubscriptionListener.connect;
• removed: TimeseriesService.seriesResolver(), which exposed the internal cache and had no callers;
• inlined: BinaryIngestOptions.executorOptions() into its only caller, since the ingestor now lives in another package.

The other packages keep only value types a caller names or receives, which stay public: DatahubApiException, IngestOptions, BinaryIngestOptions, IngestResult, SubscriptionMessage, SubscriptionError, Datapoint, UuidV7.

The SDK's AGENTS.md now states the rule, so new plumbing stays package-private.

Source compatibility

• DatahubClient and DatahubConfig imports are unchanged, and those are what most callers import.
• Service types, BinaryIngestBuffer and SubscriptionListener now import from sdk.client instead of sdk.services, sdk.ingest or sdk.subscriptions. In-repo callers (datahub-analysis, datahub-rvm-converter tests) are updated.
• Nothing has been published yet, so no released artifact is affected.

Docs

datahub-sdk-docs needs an update. Four snippets import moved types:

• docs/guides/ingest-timeseries.mdx and docs/reference/timeseries.md: sdk.ingest.BinaryIngestBuffer → sdk.client.BinaryIngestBuffer;
• docs/guides/realtime-subscriptions.mdx and docs/reference/subscriptions.md: sdk.subscriptions.SubscriptionListener → sdk.client.SubscriptionListener.

datahub-docs (operators): no change.

Verification

• The full ./gradlew build is green.
• SDK tests (113, one skipped: the backend-gated SubscriptionListenIT), datahub-analysis tests (46) and datahub-rvm-converter tests pass.
• Rebased onto main after build(sdk): make datahub-sdk publishable to Maven Central, with locally signed, CI-verified releases #148 and fix(sdk): log spool warnings through SLF4J, not System.err #150 merged. fix(sdk): log spool warnings through SLF4J, not System.err #150's SLF4J logging and build(sdk): make datahub-sdk publishable to Maven Central, with locally signed, CI-verified releases #148's doc changes are carried into the moved files, and the full ./gradlew build is green. Merges cleanly with ci: release the platform and the Java SDK together from a vX.Y.Z release #152.

🤖 Generated with Claude Code