docs: make every example compile against the SDK the docs describe

docs/advanced/asset-health-score.mdx

@@ -81,10 +81,10 @@ double bearingTemp = Double.parseDouble(pts.get(pts.size() - 1).getValue());
 // The latest datapoint, per signal; the scoring arithmetic below is shown in Python.
 use intellistream_datahub_sdk::generic::{DataWrapper, IdAndExtId};
 
-let latest = api.time_series
+let page = api.time_series
     .retrieve_latest_datapoint(&DataWrapper::from(vec![
-        IdAndExtId::from_external_id("pump_07_bearing_temp_c")])).await?
-    .get_items().remove(0);
+        IdAndExtId::from_external_id("pump_07_bearing_temp_c")])).await?;
+let latest = &page.get_items()[0];
 let bearing_temp = latest.datapoints.last().and_then(|p| p.value).unwrap_or(f64::NAN);
 ```
 

docs/advanced/demand-forecasting.mdx

@@ -88,9 +88,9 @@ let filter = RetrieveFilter {
     limit: Some(100_000),
     ..Default::default()
 };
-let history = api.time_series
-    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?
-    .get_items().remove(0);
+let page = api.time_series
+    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?;
+let history = &page.get_items()[0];
 ```
 
 </TabItem>

docs/advanced/kmeans-clustering.mdx

@@ -97,9 +97,9 @@ let filter = RetrieveFilter {
     granularity: Some("30d".into()),
     ..Default::default()
 };
-let sig = api.time_series
-    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?
-    .get_items().remove(0);
+let page = api.time_series
+    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?;
+let sig = &page.get_items()[0];
 ```
 
 </TabItem>
@@ -120,8 +120,7 @@ for asset, d in zip(assets, dist):
             event_time=pd.Timestamp.now(tz="UTC"),
             metadata={"asset": asset, "cohort": str(int(km.labels_[assets.index(asset)]))})])
 
-outliers = list(client.events.filter(intellistream_datahub_sdk.EventFilter(
-    basic_filter=intellistream_datahub_sdk.BasicEventFilter(type="peer_outlier"), limit=100)))
+outliers = list(client.events.filter(type="peer_outlier", limit=100))
 print(f"{len(outliers)} peer outlier(s) on record")
 ```
 

docs/advanced/lstm-anomaly-detection.mdx

@@ -91,9 +91,9 @@ let filter = RetrieveFilter {
     limit: Some(100_000),
     ..Default::default()
 };
-let series = api.time_series
-    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?
-    .get_items().remove(0);
+let page = api.time_series
+    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?;
+let series = &page.get_items()[0];
 ```
 
 </TabItem>

docs/advanced/lstm-forecasting.mdx

@@ -94,9 +94,9 @@ let filter = RetrieveFilter {
     limit: Some(100_000),
     ..Default::default()
 };
-let series = api.time_series
-    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?
-    .get_items().remove(0);
+let page = api.time_series
+    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?;
+let series = &page.get_items()[0];
 ```
 
 </TabItem>

docs/advanced/pca-process-monitoring.mdx

@@ -100,9 +100,9 @@ let filter = RetrieveFilter {
     limit: Some(100_000),
     ..Default::default()
 };
-let pts = api.time_series
-    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?
-    .get_items().remove(0);
+let page = api.time_series
+    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?;
+let pts = &page.get_items()[0];
 ```
 
 </TabItem>
@@ -154,8 +154,7 @@ if t2(znew)[-1] > T2_LIMIT or spe(znew)[-1] > SPE_LIMIT:
                   "top_contributor": culprit})])
 
 # the seeded fault sits in the last ten hours, so the deviation must be on record
-found = list(client.events.filter(intellistream_datahub_sdk.EventFilter(
-    basic_filter=intellistream_datahub_sdk.BasicEventFilter(type="process_deviation"), limit=10)))
+found = list(client.events.filter(type="process_deviation", limit=10))
 assert found, "the seeded fault should have raised a process_deviation event"
 print(f"{len(found)} process deviation(s) on record, latest names {found[-1].metadata['top_contributor']}")
 ```

docs/advanced/predictive-maintenance.mdx

@@ -91,9 +91,9 @@ let filter = RetrieveFilter {
     limit: Some(100_000),
     ..Default::default()
 };
-let series = api.time_series
-    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?
-    .get_items().remove(0);
+let page = api.time_series
+    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?;
+let series = &page.get_items()[0];
 ```
 
 </TabItem>

docs/advanced/random-forest-soft-sensor.mdx

@@ -94,9 +94,9 @@ let filter = RetrieveFilter {
     limit: Some(100_000),
     ..Default::default()
 };
-let pts = api.time_series
-    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?
-    .get_items().remove(0);
+let page = api.time_series
+    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?;
+let pts = &page.get_items()[0];
 ```
 
 </TabItem>

docs/advanced/sustained-alarm-window.mdx

@@ -163,6 +163,7 @@ class SustainedHigh:
 use chrono::{DateTime, Duration, Utc};
 use intellistream_datahub_sdk::events::Event;
 use std::collections::VecDeque;
+use intellistream_datahub_sdk::ApiService;
 
 const LIMIT: f64 = 4.5;
 const CLEAR_BELOW: f64 = 4.2;
@@ -213,10 +214,10 @@ impl SustainedHigh {
         let peak = self.recent.iter().map(|(_, v)| *v).fold(f64::MIN, f64::max);
 
         let mut event = Event::new(
-            format!("sustained_high_{}_{}", self.series_id, at.timestamp()));
-        event.r#type = Some("sustained_high".into());
+            format!("sustained_high_{}_{}", self.series_id, at.timestamp()),
+            "sustained_high".into(),
+            at);
         event.status = Some("open".into());
-        event.set_event_time(at);
         event.add_metadata("series".into(), self.series_id.clone());
         event.add_metadata("limit".into(), LIMIT.to_string());
         event.add_metadata("window_minutes".into(), "20".into());
@@ -315,17 +316,15 @@ let filter = RetrieveFilter {
     end: Some(Utc::now()),
     ..Default::default()
 };
-let series = api.time_series
-    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?
-    .get_items().remove(0);
+let page = api.time_series
+    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?;
+let series = &page.get_items()[0];
 
 let mut detector = SustainedHigh::new(SERIES);
 let (mut raised, mut crossings, mut previous) = (0, 0, 0.0_f64);
 for p in &series.datapoints {
-    let millis = p.timestamp.parse::<i64>()?;
-    let at = Utc.timestamp_millis_opt(millis).single().expect("valid time");
-    let value = p.value.as_deref()
-        .and_then(|v| v.parse::<f64>().ok()).unwrap_or(0.0);
+    let at = p.timestamp;
+    let value = p.value.unwrap_or(0.0);
     if previous <= LIMIT && value > LIMIT { crossings += 1; }
     previous = value;
     if detector.push(&api, at, value).await.is_some() { raised += 1; }
@@ -371,8 +370,7 @@ if (found.getItems().size() != 1) {
 <TabItem value="python" label="Python">
 
 ```python
-found = list(client.events.filter(intellistream_datahub_sdk.EventFilter(
-    basic_filter=intellistream_datahub_sdk.BasicEventFilter(type="sustained_high"), limit=100)))
+found = list(client.events.filter(type="sustained_high", limit=100))
 
 for e in found:
     print(e.external_id, e.metadata)
@@ -386,10 +384,10 @@ assert len(found) == 1, f"expected one finding, found {len(found)}"
 <TabItem value="rust" label="Rust">
 
 ```rust
-use intellistream_datahub_sdk::filters::{BasicEventFilter, EventFilter};
+use intellistream_datahub_sdk::filters::{EventFilter, EventFilterForm};
 
-let filter = EventFilter::default()
-    .set_filter(BasicEventFilter {
+let filter = EventFilterForm::default()
+    .set_filter(EventFilter {
         r#type: Some(vec!["sustained_high".into()]), ..Default::default() })
     .set_limit(100)
     .build();

docs/advanced/xgboost-failure-prediction.mdx

@@ -95,9 +95,9 @@ let filter = RetrieveFilter {
     granularity: Some("7d".into()),
     ..Default::default()
 };
-let agg = api.time_series
-    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?
-    .get_items().remove(0);
+let page = api.time_series
+    .retrieve_datapoints(&DataWrapper::from(vec![filter])).await?;
+let agg = &page.get_items()[0];
 ```
 
 </TabItem>
@@ -112,8 +112,7 @@ events and label each `(pump, day)` accordingly.
 # failures: DataFrame of (pump, failed_on), pulled from /events (type = esp_failure)
 failures = pd.DataFrame([
     {"pump": e.metadata.get("pump"), "failed_on": pd.to_datetime(e.event_time, utc=True)}
-    for e in client.events.filter(intellistream_datahub_sdk.EventFilter(
-        intellistream_datahub_sdk.BasicEventFilter(type="esp_failure"), limit=1000))])
+    for e in client.events.filter(type="esp_failure", limit=1000)])
 
 # one feature row per pump per day across the history you have
 training_grid = [(p, d) for p in ["pump_esp_a12"]

docs/guides/attach-files.mdx

@@ -37,7 +37,7 @@ var uploaded = client.files().upload(
         .description("ESP A-12 calibration certificate")
         .build());
 
-System.out.println("stored as id " + uploaded.getItems().iterator().next().getId());
+System.out.println("stored as id " + uploaded.getItems().get(0).getId());
 ```
 
 </TabItem>
@@ -63,7 +63,7 @@ use intellistream_datahub_sdk::files::FileUpload;
 
 // MIME type is inferred from the file content
 let mut upload = FileUpload::new_with_destination_path(
-    "calibration_a12.pdf", "/certificates/2026/");
+    "calibration_a12.pdf", "/certificates/2026/")?;
 upload.set_external_id("calibration_pump_esp_a12".into());
 upload.set_file_name("calibration_a12.pdf".into());
 upload.set_data_set_id(42);
@@ -139,7 +139,7 @@ string (the endpoint also accepts an external id in that position).
 <TabItem value="java" label="Java">
 
 ```java
-long id = uploaded.getItems().iterator().next().getId();
+long id = uploaded.getItems().get(0).getId();
 byte[] bytes = client.files().download(String.valueOf(id));
 Files.write(Path.of("calibration_a12.pdf"), bytes);
 ```

docs/guides/correlate-alarms.mdx

@@ -96,10 +96,10 @@ subsystem both alarms belong to, the likely common cause.
 
 ```java
 Set<String> aNodes = na.nodes().stream()
-    .map(Resource::getExternalId).collect(Collectors.toSet());
+    .map(NodeModel::getExternalId).collect(Collectors.toSet());
 
 Set<String> shared = nb.nodes().stream()
-    .map(Resource::getExternalId)
+    .map(NodeModel::getExternalId)
     .filter(aNodes::contains)
     .collect(Collectors.toSet());
 shared.remove("sensor_a");

docs/guides/model-assets-graph.mdx

@@ -26,17 +26,17 @@ well in code, not because the server requires it.
 <TabItem value="java" label="Java">
 
 ```java
-ResourceForm plant = new ResourceForm();
+Resource plant = new Resource();
 plant.setExternalId("plant_oslo");
 plant.setName("Oslo Plant");
 plant.setLabels(List.of("Plant"));       // at least one label is required
 
-ResourceForm line = new ResourceForm();
+Resource line = new Resource();
 line.setExternalId("line_a");
 line.setName("Assembly line A");
 line.setLabels(List.of("Line"));
 
-ResourceForm press = new ResourceForm();
+Resource press = new Resource();
 press.setExternalId("press_07");
 press.setName("Hydraulic press 07");
 press.setLabels(List.of("Machine"));
@@ -126,9 +126,9 @@ it with a relationship (`press_07` → `PRODUCES` → `press_07_oil_temp`), then
 <TabItem value="java" label="Java">
 
 ```java
-Timeseries oilTemp = new Timeseries()
-        .setExternalId("press_07_oil_temp")
-        .setName("Press 07 oil temperature");
+Timeseries oilTemp = new Timeseries();
+oilTemp.setExternalId("press_07_oil_temp");
+oilTemp.setName("Press 07 oil temperature");
 oilTemp.setUnit("celsius");
 oilTemp.setUnitExternalId("temperature_deg_c");
 client.timeseries().create(List.of(oilTemp));

docs/guides/work-with-units.mdx

@@ -54,7 +54,9 @@ and Rust examples set `float`); it describes what the numbers mean.
 <TabItem value="java" label="Java">
 
 ```java
-var series = Timeseries.of("wellhead_pressure_bar").name("Wellhead pressure");
+var series = new Timeseries();
+series.setExternalId("wellhead_pressure_bar");
+series.setName("Wellhead pressure");
 series.setUnit("bar");
 series.setUnitExternalId("pressure_bar");
 client.timeseries().create(series);
@@ -101,9 +103,9 @@ Resolve a unit you already know, by external id, or by numeric id.
 
 ```java
 UnitModel celsius = client.units().byIds(List.of(
-        IdCollection.createFromExternalId("temperature_deg_c"))).getItems().iterator().next();
+        IdCollection.createFromExternalId("temperature_deg_c"))).getItems().get(0);
 UnitModel byId = client.units().byIds(List.of(
-        IdCollection.createFromId(7))).getItems().iterator().next();
+        IdCollection.createFromId(7))).getItems().get(0);
 ```
 
 </TabItem>
@@ -112,7 +114,7 @@ UnitModel byId = client.units().byIds(List.of(
 ```python
 import intellistream_datahub_sdk
 
-celsius = client.units.by_external_ids("temperature_deg_c")
+celsius = client.units.by_external_id("temperature_deg_c")
 by_id = client.units.by_ids([intellistream_datahub_sdk.IdCollection(id=7)])
 ```
 

docs/industries/agriculture-food/precision-farming.mdx

@@ -42,9 +42,13 @@ A farm *contains* fields; each field's sensors are series.
 <TabItem value="java" label="Java">
 
 ```java
-var moisture = Timeseries.of("field_north_40_soil_moisture").name("North 40 soil moisture");
+var moisture = new Timeseries();
+moisture.setExternalId("field_north_40_soil_moisture");
+moisture.setName("North 40 soil moisture");
 moisture.setUnit("pct");
-var soilTemp = Timeseries.of("field_north_40_soil_temp_c").name("North 40 soil temperature");
+var soilTemp = new Timeseries();
+soilTemp.setExternalId("field_north_40_soil_temp_c");
+soilTemp.setName("North 40 soil temperature");
 soilTemp.setUnit("deg_c");
 client.timeseries().create(moisture, soilTemp);
 
@@ -130,7 +134,7 @@ client.files.upload_file(intellistream_datahub_sdk.FileUpload(
 use intellistream_datahub_sdk::files::FileUpload;
 
 let mut upload = FileUpload::new_with_destination_path(
-    "north_40_2026_06_28.tif", "/fields/north_40/scans/");
+    "north_40_2026_06_28.tif", "/fields/north_40/scans/")?;
 upload.external_id = "scan_north_40_2026_06_28".into();
 upload.name = "2026_06_28.tif".into();
 api.files.upload_file(upload).await?;

docs/industries/agriculture-food/salmon-farming.mdx

@@ -92,12 +92,13 @@ use chrono::Utc;
 let mut listener = api.subscriptions.listen(&["farm_hardanger_pens"]).await?;
 while let Some(Ok(msg)) = listener.next().await {
     if oxygen_below(&msg.payload, 6.0) {              // mg/L — danger approaching
-        let mut alarm = Event::new(format!("low_oxygen_h07_{}", Utc::now().timestamp()));
-        alarm.r#type = Some("low_oxygen".into());
+        let mut alarm = Event::new(
+            format!("low_oxygen_h07_{}", Utc::now().timestamp()),
+            "low_oxygen".into(),
+            Utc::now());
         alarm.status = Some("critical".into());
         alarm.add_metadata("pen".into(), "pen_h_07".into());
         alarm.add_metadata("do_mg_l".into(), "5.6".into());
-        alarm.set_event_time(Utc::now());
         api.events.create(&vec![alarm]).await?;       // triggers aeration
     }
     listener.ack(&[msg.message_id.as_str()]).await?;
@@ -117,9 +118,13 @@ See [Query & aggregate](/guides/query-and-aggregate).
 <TabItem value="java" label="Java">
 
 ```java
-var feed = Timeseries.of("pen_h_07_feed_kg").name("Pen H-07 feed");
+var feed = new Timeseries();
+feed.setExternalId("pen_h_07_feed_kg");
+feed.setName("Pen H-07 feed");
 feed.setUnit("kg");
-var biomass = Timeseries.of("pen_h_07_biomass_kg").name("Pen H-07 biomass");
+var biomass = new Timeseries();
+biomass.setExternalId("pen_h_07_biomass_kg");
+biomass.setName("Pen H-07 biomass");
 biomass.setUnit("kg");
 client.timeseries().create(feed, biomass);