feat: BuildKit client + integration test suite (651 tests)

BuildKitClient CLI wrapper for buildctl.
Docker compose stack (9 services) for integration testing.
Comprehensive test suite: wiremock tests for Matrix/La Suite/S3/client,
integration tests for Kratos/Hydra/Gitea/OpenSearch/Prometheus/Loki/
Grafana/LiveKit.

Bump: sunbeam-sdk v0.12.0

Cargo.lock

@@ -3591,7 +3591,7 @@ dependencies = [
 
 [[package]]
 name = "sunbeam-sdk"
-version = "0.10.0"
+version = "0.11.0"
 dependencies = [
  "base64",
  "bytes",

sunbeam-sdk/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sunbeam-sdk"
-version = "0.11.0"
+version = "0.12.0"
 edition = "2024"
 description = "Sunbeam SDK — reusable library for cluster management"
 repository = "https://src.sunbeam.pt/studio/cli"

sunbeam-sdk/tests/config/identity.schema.json

@@ -0,0 +1,27 @@
+{
+  "$id": "https://schemas.sunbeam.pt/default.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Default identity",
+  "type": "object",
+  "properties": {
+    "traits": {
+      "type": "object",
+      "properties": {
+        "email": {
+          "type": "string",
+          "format": "email",
+          "title": "Email",
+          "ory.sh/kratos": {
+            "credentials": {
+              "password": { "identifier": true }
+            },
+            "recovery": { "via": "email" },
+            "verification": { "via": "email" }
+          }
+        }
+      },
+      "required": ["email"],
+      "additionalProperties": true
+    }
+  }
+}

sunbeam-sdk/tests/config/kratos.yml

@@ -0,0 +1,26 @@
+dsn: memory
+
+serve:
+  admin:
+    port: 4434
+    host: 0.0.0.0
+  public:
+    port: 4433
+    host: 0.0.0.0
+    base_url: http://localhost:4433/
+
+identity:
+  default_schema_id: default
+  schemas:
+    - id: default
+      url: file:///etc/config/kratos/identity.schema.json
+
+selfservice:
+  default_browser_return_url: http://localhost:4455/
+  flows:
+    registration:
+      enabled: true
+
+courier:
+  smtp:
+    connection_uri: smtp://localhost:1025/?disable_starttls=true

sunbeam-sdk/tests/config/livekit.yaml

@@ -0,0 +1,7 @@
+port: 7880
+bind_addresses:
+  - 0.0.0.0
+keys:
+  devkey: devsecret
+logging:
+  level: info

sunbeam-sdk/tests/config/loki.yml

@@ -0,0 +1,34 @@
+auth_enabled: false
+
+server:
+  http_listen_port: 3100
+
+common:
+  ring:
+    kvstore:
+      store: inmemory
+    replication_factor: 1
+    instance_addr: 127.0.0.1
+  path_prefix: /tmp/loki
+
+ingester:
+  lifecycler:
+    ring:
+      kvstore:
+        store: inmemory
+      replication_factor: 1
+    min_ready_duration: 0s
+
+schema_config:
+  configs:
+    - from: "2020-01-01"
+      store: tsdb
+      object_store: filesystem
+      schema: v13
+      index:
+        prefix: index_
+        period: 24h
+
+storage_config:
+  filesystem:
+    directory: /tmp/loki/chunks

sunbeam-sdk/tests/config/prometheus.yml

@@ -0,0 +1,8 @@
+global:
+  scrape_interval: 5s
+  evaluation_interval: 5s
+
+scrape_configs:
+  - job_name: prometheus
+    static_configs:
+      - targets: ['localhost:9090']

sunbeam-sdk/tests/docker-compose.yml

@@ -0,0 +1,157 @@
+# Lightweight integration test stack for sunbeam-sdk service clients.
+# All services use in-memory/SQLite storage — fully ephemeral.
+#
+# Usage:
+#   docker compose -f sunbeam-sdk/tests/docker-compose.yml up -d
+#   cargo test -p sunbeam-sdk --features integration --test integration
+#   docker compose -f sunbeam-sdk/tests/docker-compose.yml down
+
+services:
+  # ── Identity (Ory Kratos) ────────────────────────────────────────────
+  kratos:
+    image: oryd/kratos:v1.3.1
+    command: serve -c /etc/config/kratos/kratos.yml --dev --watch-courier
+    ports:
+      - "4434:4434"   # admin API
+      - "4433:4433"   # public API
+    volumes:
+      - ./config/kratos.yml:/etc/config/kratos/kratos.yml:ro
+      - ./config/identity.schema.json:/etc/config/kratos/identity.schema.json:ro
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:4434/health/alive"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  # ── Auth / OAuth2 (Ory Hydra) ───────────────────────────────────────
+  hydra:
+    image: oryd/hydra:v2.3.0
+    command: serve all --dev
+    ports:
+      - "4444:4444"   # public (OIDC)
+      - "4445:4445"   # admin API
+    environment:
+      DSN: memory
+      URLS_SELF_ISSUER: http://localhost:4444
+      URLS_LOGIN: http://localhost:3000/login
+      URLS_CONSENT: http://localhost:3000/consent
+      SECRETS_SYSTEM: integration-test-secret-32bytes!
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:4445/health/alive"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  # ── Git Forge (Gitea) ───────────────────────────────────────────────
+  gitea:
+    image: gitea/gitea:1.23-rootless
+    ports:
+      - "3000:3000"
+    environment:
+      GITEA__database__DB_TYPE: sqlite3
+      GITEA__database__PATH: /tmp/gitea.db
+      GITEA__server__HTTP_PORT: "3000"
+      GITEA__server__ROOT_URL: http://localhost:3000
+      GITEA__server__DISABLE_SSH: "true"
+      GITEA__security__INSTALL_LOCK: "true"
+      GITEA__service__DISABLE_REGISTRATION: "false"
+      GITEA__log__LEVEL: Warn
+    tmpfs:
+      - /tmp
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3000/api/v1/version"]
+      interval: 5s
+      timeout: 3s
+      retries: 15
+
+  # ── Search (OpenSearch) ─────────────────────────────────────────────
+  opensearch:
+    image: opensearchproject/opensearch:2.19.1
+    ports:
+      - "9200:9200"
+    environment:
+      discovery.type: single-node
+      DISABLE_SECURITY_PLUGIN: "true"
+      DISABLE_INSTALL_DEMO_CONFIG: "true"
+      OPENSEARCH_JAVA_OPTS: -Xms256m -Xmx256m
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:9200/_cluster/health"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  # ── S3-compatible Storage (MinIO) ───────────────────────────────────
+  minio:
+    image: minio/minio:latest
+    command: server /data --console-address :9001
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:9000/minio/health/live"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  # ── Metrics (Prometheus) ────────────────────────────────────────────
+  prometheus:
+    image: prom/prometheus:v3.2.1
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./config/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:9090/api/v1/status/buildinfo"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  # ── Logs (Loki) ─────────────────────────────────────────────────────
+  loki:
+    image: grafana/loki:3.4.3
+    command: -config.file=/etc/loki/loki.yml
+    user: "0"
+    ports:
+      - "3100:3100"
+    volumes:
+      - ./config/loki.yml:/etc/loki/loki.yml:ro
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3100/ready"]
+      interval: 5s
+      timeout: 3s
+      retries: 15
+
+  # ── Dashboards (Grafana) ────────────────────────────────────────────
+  grafana:
+    image: grafana/grafana:11.5.2
+    ports:
+      - "3001:3001"
+    environment:
+      GF_SERVER_HTTP_PORT: "3001"
+      GF_AUTH_ANONYMOUS_ENABLED: "true"
+      GF_AUTH_ANONYMOUS_ORG_ROLE: Admin
+      GF_SECURITY_ADMIN_PASSWORD: admin
+      GF_DATABASE_TYPE: sqlite3
+      GF_LOG_LEVEL: warn
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3001/api/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  # ── Media (LiveKit) ─────────────────────────────────────────────────
+  livekit:
+    image: livekit/livekit-server:v1.8.4
+    command: --config /etc/livekit.yaml --dev
+    ports:
+      - "7880:7880"
+    volumes:
+      - ./config/livekit.yaml:/etc/livekit.yaml:ro
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:7880"]
+      interval: 5s
+      timeout: 3s
+      retries: 10

sunbeam-sdk/tests/helpers/mod.rs

@@ -0,0 +1,105 @@
+//! Shared test helpers for integration tests.
+
+#![allow(dead_code)]
+
+/// Poll a URL until it returns 200, or panic after `timeout`.
+pub async fn wait_for_healthy(url: &str, timeout: std::time::Duration) {
+    let client = reqwest::Client::new();
+    let deadline = tokio::time::Instant::now() + timeout;
+    loop {
+        if tokio::time::Instant::now() > deadline {
+            panic!("Service at {url} did not become healthy within {timeout:?}");
+        }
+        if let Ok(resp) = client.get(url).send().await {
+            if resp.status().is_success() {
+                return;
+            }
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+    }
+}
+
+pub const TIMEOUT: std::time::Duration = std::time::Duration::from_secs(60);
+
+// Gitea bootstrap constants
+pub const GITEA_ADMIN_USER: &str = "testadmin";
+pub const GITEA_ADMIN_PASS: &str = "testpass123";
+pub const GITEA_ADMIN_EMAIL: &str = "admin@test.local";
+
+/// Bootstrap Gitea admin user + PAT. Returns the PAT string.
+pub async fn setup_gitea_pat() -> String {
+    wait_for_healthy("http://localhost:3000/api/v1/version", TIMEOUT).await;
+    let http = reqwest::Client::new();
+
+    // Register user via public API
+    let _ = http
+        .post("http://localhost:3000/user/sign_up")
+        .form(&[
+            ("user_name", GITEA_ADMIN_USER),
+            ("password", GITEA_ADMIN_PASS),
+            ("retype", GITEA_ADMIN_PASS),
+            ("email", GITEA_ADMIN_EMAIL),
+        ])
+        .send()
+        .await;
+
+    // Create PAT using basic auth
+    let resp = http
+        .post(format!(
+            "http://localhost:3000/api/v1/users/{GITEA_ADMIN_USER}/tokens"
+        ))
+        .basic_auth(GITEA_ADMIN_USER, Some(GITEA_ADMIN_PASS))
+        .json(&serde_json::json!({
+            "name": format!("test-{}", std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_millis()),
+            "scopes": ["all"]
+        }))
+        .send()
+        .await
+        .unwrap();
+
+    if !resp.status().is_success() {
+        panic!(
+            "PAT creation failed: {}",
+            resp.text().await.unwrap_or_default()
+        );
+    }
+
+    let body: serde_json::Value = resp.json().await.unwrap();
+    body["sha1"]
+        .as_str()
+        .or_else(|| body["token"].as_str())
+        .expect("PAT response missing sha1/token field")
+        .to_string()
+}
+
+/// Generate a LiveKit JWT for testing.
+pub fn livekit_test_token() -> String {
+    use sunbeam_sdk::media::types::VideoGrants;
+    use sunbeam_sdk::media::LiveKitClient;
+    let grants = VideoGrants {
+        room_create: Some(true),
+        room_list: Some(true),
+        room_join: Some(true),
+        can_publish: Some(true),
+        can_subscribe: Some(true),
+        can_publish_data: Some(true),
+        room_admin: Some(true),
+        room_record: Some(true),
+        room: None,
+    };
+    LiveKitClient::generate_access_token("devkey", "devsecret", "test-user", &grants, 600)
+        .expect("JWT generation failed")
+}
+
+/// Generate a unique name for test resources to avoid collisions.
+pub fn unique_name(prefix: &str) -> String {
+    format!(
+        "{}-{}",
+        prefix,
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_millis()
+            % 100000
+    )
+}

sunbeam-sdk/tests/integration.rs

@@ -0,0 +1,528 @@
+//! Integration tests for sunbeam-sdk service clients.
+//!
+//! Requires the test stack running:
+//!   docker compose -f sunbeam-sdk/tests/docker-compose.yml up -d
+//!
+//! Run with:
+//!   cargo test -p sunbeam-sdk --features integration --test integration
+#![cfg(feature = "integration")]
+
+use sunbeam_sdk::client::{AuthMethod, ServiceClient};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/// Poll a URL until it returns 200, or panic after `timeout`.
+async fn wait_for_healthy(url: &str, timeout: std::time::Duration) {
+    let client = reqwest::Client::new();
+    let deadline = tokio::time::Instant::now() + timeout;
+    loop {
+        if tokio::time::Instant::now() > deadline {
+            panic!("Service at {url} did not become healthy within {timeout:?}");
+        }
+        if let Ok(resp) = client.get(url).send().await {
+            if resp.status().is_success() {
+                return;
+            }
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+    }
+}
+
+const TIMEOUT: std::time::Duration = std::time::Duration::from_secs(60);
+
+// ---------------------------------------------------------------------------
+// Kratos
+// ---------------------------------------------------------------------------
+
+mod kratos {
+    use super::*;
+    use sunbeam_sdk::identity::KratosClient;
+
+    fn client() -> KratosClient {
+        KratosClient::from_parts("http://localhost:4434".into(), AuthMethod::None)
+    }
+
+    #[tokio::test]
+    async fn health() {
+        wait_for_healthy("http://localhost:4434/health/alive", TIMEOUT).await;
+        let c = client();
+        let status = c.alive().await.unwrap();
+        assert_eq!(status.status, "ok");
+    }
+
+    #[tokio::test]
+    async fn identity_crud() {
+        wait_for_healthy("http://localhost:4434/health/alive", TIMEOUT).await;
+        let c = client();
+
+        // Create
+        let body = sunbeam_sdk::identity::types::CreateIdentityBody {
+            schema_id: "default".into(),
+            traits: serde_json::json!({"email": "integration-test@example.com"}),
+            state: Some("active".into()),
+            metadata_public: None,
+            metadata_admin: None,
+            credentials: None,
+            verifiable_addresses: None,
+            recovery_addresses: None,
+        };
+        let identity = c.create_identity(&body).await.unwrap();
+        assert!(!identity.id.is_empty());
+        let id = identity.id.clone();
+
+        // Get
+        let fetched = c.get_identity(&id).await.unwrap();
+        assert_eq!(fetched.id, id);
+
+        // List
+        let list = c.list_identities(None, None).await.unwrap();
+        assert!(list.iter().any(|i| i.id == id));
+
+        // Update
+        let update = sunbeam_sdk::identity::types::UpdateIdentityBody {
+            schema_id: "default".into(),
+            traits: serde_json::json!({"email": "updated@example.com"}),
+            state: "active".into(),
+            metadata_public: None,
+            metadata_admin: None,
+            credentials: None,
+        };
+        let updated = c.update_identity(&id, &update).await.unwrap();
+        assert_eq!(updated.traits["email"], "updated@example.com");
+
+        // Delete
+        c.delete_identity(&id).await.unwrap();
+        let list = c.list_identities(None, None).await.unwrap();
+        assert!(!list.iter().any(|i| i.id == id));
+    }
+
+    #[tokio::test]
+    async fn schemas() {
+        wait_for_healthy("http://localhost:4434/health/alive", TIMEOUT).await;
+        let c = client();
+        let schemas = c.list_schemas().await.unwrap();
+        assert!(!schemas.is_empty());
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Hydra
+// ---------------------------------------------------------------------------
+
+mod hydra {
+    use super::*;
+    use sunbeam_sdk::auth::hydra::HydraClient;
+    use sunbeam_sdk::auth::hydra::types::OAuth2Client;
+
+    fn client() -> HydraClient {
+        HydraClient::from_parts("http://localhost:4445".into(), AuthMethod::None)
+    }
+
+    #[tokio::test]
+    async fn oauth2_client_crud() {
+        wait_for_healthy("http://localhost:4445/health/alive", TIMEOUT).await;
+        let c = client();
+
+        // Create
+        let body = OAuth2Client {
+            client_name: Some("test-client".into()),
+            grant_types: Some(vec!["authorization_code".into()]),
+            redirect_uris: Some(vec!["http://localhost:9876/callback".into()]),
+            scope: Some("openid email".into()),
+            token_endpoint_auth_method: Some("none".into()),
+            ..Default::default()
+        };
+        let created = c.create_client(&body).await.unwrap();
+        let cid = created.client_id.unwrap();
+        assert!(!cid.is_empty());
+
+        // Get
+        let fetched = c.get_client(&cid).await.unwrap();
+        assert_eq!(fetched.client_name, Some("test-client".into()));
+
+        // List
+        let list = c.list_clients(None, None).await.unwrap();
+        assert!(list.iter().any(|cl| cl.client_id.as_deref() == Some(&cid)));
+
+        // Update
+        let mut updated_body = fetched.clone();
+        updated_body.client_name = Some("renamed-client".into());
+        let updated = c.update_client(&cid, &updated_body).await.unwrap();
+        assert_eq!(updated.client_name, Some("renamed-client".into()));
+
+        // Delete
+        c.delete_client(&cid).await.unwrap();
+        let list = c.list_clients(None, None).await.unwrap();
+        assert!(!list.iter().any(|cl| cl.client_id.as_deref() == Some(&cid)));
+    }
+
+    #[tokio::test]
+    async fn token_introspect_inactive() {
+        wait_for_healthy("http://localhost:4445/health/alive", TIMEOUT).await;
+        let c = client();
+        let result = c.introspect_token("bogus-token").await.unwrap();
+        assert!(!result.active);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Gitea
+// ---------------------------------------------------------------------------
+
+mod gitea {
+    use super::*;
+    use sunbeam_sdk::gitea::GiteaClient;
+
+    const ADMIN_USER: &str = "testadmin";
+    const ADMIN_PASS: &str = "testpass123";
+    const ADMIN_EMAIL: &str = "admin@test.local";
+
+    /// Bootstrap admin user + PAT. Returns the PAT string.
+    async fn setup_gitea() -> String {
+        wait_for_healthy("http://localhost:3000/api/v1/version", TIMEOUT).await;
+        let http = reqwest::Client::new();
+
+        // Register user via public API (DISABLE_REGISTRATION=false)
+        let _ = http
+            .post("http://localhost:3000/user/sign_up")
+            .form(&[
+                ("user_name", ADMIN_USER),
+                ("password", ADMIN_PASS),
+                ("retype", ADMIN_PASS),
+                ("email", ADMIN_EMAIL),
+            ])
+            .send()
+            .await;
+
+        // Create PAT using basic auth
+        let resp = http
+            .post(format!(
+                "http://localhost:3000/api/v1/users/{ADMIN_USER}/tokens"
+            ))
+            .basic_auth(ADMIN_USER, Some(ADMIN_PASS))
+            .json(&serde_json::json!({
+                "name": format!("test-{}", std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_millis()),
+                "scopes": ["all"]
+            }))
+            .send()
+            .await
+            .unwrap();
+
+        if !resp.status().is_success() {
+            panic!("PAT creation failed: {}", resp.text().await.unwrap_or_default());
+        }
+
+        let body: serde_json::Value = resp.json().await.unwrap();
+        body["sha1"]
+            .as_str()
+            .or_else(|| body["token"].as_str())
+            .expect("PAT response missing sha1/token field")
+            .to_string()
+    }
+
+    #[tokio::test]
+    async fn repo_crud() {
+        let pat = setup_gitea().await;
+        let c = GiteaClient::from_parts(
+            "http://localhost:3000/api/v1".into(),
+            AuthMethod::Token(pat),
+        );
+
+        // Authenticated user
+        let me = c.get_authenticated_user().await.unwrap();
+        assert_eq!(me.login, ADMIN_USER);
+
+        // Create repo
+        let body = sunbeam_sdk::gitea::types::CreateRepoBody {
+            name: "integration-test".into(),
+            description: Some("test repo".into()),
+            auto_init: Some(true),
+            ..Default::default()
+        };
+        let repo = c.create_user_repo(&body).await.unwrap();
+        assert_eq!(repo.name, "integration-test");
+
+        // Get repo
+        let fetched = c.get_repo(ADMIN_USER, "integration-test").await.unwrap();
+        assert_eq!(fetched.full_name, format!("{ADMIN_USER}/integration-test"));
+
+        // Search repos
+        let results = c.search_repos("integration", None).await.unwrap();
+        assert!(!results.data.is_empty());
+
+        // Delete repo
+        c.delete_repo(ADMIN_USER, "integration-test").await.unwrap();
+    }
+}
+
+// ---------------------------------------------------------------------------
+// OpenSearch
+// ---------------------------------------------------------------------------
+
+mod opensearch {
+    use super::*;
+    use sunbeam_sdk::search::OpenSearchClient;
+
+    fn client() -> OpenSearchClient {
+        OpenSearchClient::from_parts("http://localhost:9200".into(), AuthMethod::None)
+    }
+
+    #[tokio::test]
+    async fn cluster_health() {
+        wait_for_healthy("http://localhost:9200/_cluster/health", TIMEOUT).await;
+        let c = client();
+        let health = c.cluster_health().await.unwrap();
+        assert!(!health.cluster_name.is_empty());
+    }
+
+    #[tokio::test]
+    async fn document_crud() {
+        wait_for_healthy("http://localhost:9200/_cluster/health", TIMEOUT).await;
+        let c = client();
+
+        let idx = "integration-test";
+
+        // Create index
+        let _ = c
+            .create_index(idx, &serde_json::json!({"settings": {"number_of_shards": 1, "number_of_replicas": 0}}))
+            .await
+            .unwrap();
+
+        // Index a document
+        let doc = serde_json::json!({"title": "Hello", "body": "World"});
+        let resp = c.index_doc(idx, "doc-1", &doc).await.unwrap();
+        assert_eq!(resp.result.as_deref(), Some("created"));
+
+        // Refresh to make searchable (use a raw reqwest call)
+        let _ = reqwest::Client::new()
+            .post(format!("http://localhost:9200/{idx}/_refresh"))
+            .send()
+            .await;
+
+        // Get document
+        let got = c.get_doc(idx, "doc-1").await.unwrap();
+        assert_eq!(got.source.as_ref().unwrap()["title"], "Hello");
+
+        // Search
+        let query = serde_json::json!({"query": {"match_all": {}}});
+        let results = c.search(idx, &query).await.unwrap();
+        assert!(results.hits.total.value > 0);
+
+        // Delete document
+        let del = c.delete_doc(idx, "doc-1").await.unwrap();
+        assert_eq!(del.result.as_deref(), Some("deleted"));
+
+        // Delete index
+        c.delete_index(idx).await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn cat_indices() {
+        wait_for_healthy("http://localhost:9200/_cluster/health", TIMEOUT).await;
+        let c = client();
+        let _indices = c.cat_indices().await.unwrap();
+        // Just verify it parses without error
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Prometheus
+// ---------------------------------------------------------------------------
+
+mod prometheus {
+    use super::*;
+    use sunbeam_sdk::monitoring::PrometheusClient;
+
+    fn client() -> PrometheusClient {
+        PrometheusClient::from_parts("http://localhost:9090/api/v1".into(), AuthMethod::None)
+    }
+
+    #[tokio::test]
+    async fn query_up() {
+        wait_for_healthy("http://localhost:9090/api/v1/status/buildinfo", TIMEOUT).await;
+        let c = client();
+
+        let result = c.build_info().await.unwrap();
+        assert_eq!(result.status, "success");
+
+        let result = c.query("up", None).await.unwrap();
+        assert_eq!(result.status, "success");
+    }
+
+    #[tokio::test]
+    async fn labels() {
+        wait_for_healthy("http://localhost:9090/api/v1/status/buildinfo", TIMEOUT).await;
+        let c = client();
+
+        let result = c.labels(None, None).await.unwrap();
+        assert_eq!(result.status, "success");
+    }
+
+    #[tokio::test]
+    async fn targets() {
+        wait_for_healthy("http://localhost:9090/api/v1/status/buildinfo", TIMEOUT).await;
+        let c = client();
+
+        let result = c.targets().await.unwrap();
+        assert_eq!(result.status, "success");
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Loki
+// ---------------------------------------------------------------------------
+
+mod loki {
+    use super::*;
+    use sunbeam_sdk::monitoring::LokiClient;
+
+    fn client() -> LokiClient {
+        LokiClient::from_parts("http://localhost:3100/loki/api/v1".into(), AuthMethod::None)
+    }
+
+    #[tokio::test]
+    async fn ready_and_labels() {
+        wait_for_healthy("http://localhost:3100/ready", TIMEOUT).await;
+        let c = client();
+
+        let _status = c.ready().await.unwrap();
+
+        // Loki's ring needs time to settle — retry labels a few times
+        for i in 0..10 {
+            match c.labels(None, None).await {
+                Ok(labels) => {
+                    assert_eq!(labels.status, "success");
+                    return;
+                }
+                Err(_) if i < 9 => {
+                    tokio::time::sleep(std::time::Duration::from_secs(2)).await;
+                }
+                Err(e) => panic!("loki labels failed after retries: {e}"),
+            }
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Grafana
+// ---------------------------------------------------------------------------
+
+mod grafana {
+    use super::*;
+    use sunbeam_sdk::monitoring::GrafanaClient;
+
+    fn client() -> GrafanaClient {
+        use base64::Engine;
+        let creds = base64::engine::general_purpose::STANDARD.encode("admin:admin");
+        GrafanaClient::from_parts(
+            "http://localhost:3001/api".into(),
+            AuthMethod::Header {
+                name: "Authorization",
+                value: format!("Basic {creds}"),
+            },
+        )
+    }
+
+    #[tokio::test]
+    async fn org() {
+        wait_for_healthy("http://localhost:3001/api/health", TIMEOUT).await;
+        let c = client();
+        let org = c.get_current_org().await.unwrap();
+        assert!(!org.name.is_empty());
+    }
+
+    #[tokio::test]
+    async fn folder_and_dashboard_crud() {
+        wait_for_healthy("http://localhost:3001/api/health", TIMEOUT).await;
+        let c = client();
+
+        // Create folder
+        let folder = c
+            .create_folder(&serde_json::json!({"title": "Integration Tests"}))
+            .await
+            .unwrap();
+        let folder_uid = folder.uid.clone();
+        assert!(!folder_uid.is_empty());
+
+        // Create dashboard in folder
+        let dash_body = serde_json::json!({
+            "dashboard": {
+                "title": "Test Dashboard",
+                "panels": [],
+                "schemaVersion": 30,
+            },
+            "folderUid": folder_uid,
+            "overwrite": false
+        });
+        let dash = c.create_dashboard(&dash_body).await.unwrap();
+        let dash_uid = dash.uid.clone().unwrap();
+
+        // List dashboards
+        let list = c.list_dashboards().await.unwrap();
+        assert!(list.iter().any(|d| d.uid == dash_uid));
+
+        // Delete dashboard
+        c.delete_dashboard(&dash_uid).await.unwrap();
+
+        // Delete folder
+        c.delete_folder(&folder_uid).await.unwrap();
+    }
+}
+
+// ---------------------------------------------------------------------------
+// LiveKit
+// ---------------------------------------------------------------------------
+
+mod livekit {
+    use super::*;
+    use sunbeam_sdk::media::LiveKitClient;
+    use sunbeam_sdk::media::types::VideoGrants;
+
+    fn client() -> LiveKitClient {
+        let grants = VideoGrants {
+            room_create: Some(true),
+            room_list: Some(true),
+            room_join: Some(true),
+            ..Default::default()
+        };
+        let token =
+            LiveKitClient::generate_access_token("devkey", "devsecret", "test-user", &grants, 300)
+                .expect("JWT generation failed");
+        LiveKitClient::from_parts("http://localhost:7880".into(), AuthMethod::Bearer(token))
+    }
+
+    #[tokio::test]
+    async fn room_crud() {
+        wait_for_healthy("http://localhost:7880", TIMEOUT).await;
+        let c = client();
+
+        // List rooms (empty initially)
+        let rooms = c
+            .list_rooms()
+            .await
+            .unwrap();
+        let initial_count = rooms.rooms.len();
+
+        // Create room
+        let room = c
+            .create_room(&serde_json::json!({"name": "integration-test-room"}))
+            .await
+            .unwrap();
+        assert_eq!(room.name, "integration-test-room");
+
+        // List rooms (should have one more)
+        let rooms = c.list_rooms().await.unwrap();
+        assert_eq!(rooms.rooms.len(), initial_count + 1);
+
+        // Delete room
+        c.delete_room(&serde_json::json!({"room": "integration-test-room"}))
+            .await
+            .unwrap();
+
+        // Verify deleted
+        let rooms = c.list_rooms().await.unwrap();
+        assert_eq!(rooms.rooms.len(), initial_count);
+    }
+}

sunbeam-sdk/tests/test_client.rs

@@ -0,0 +1,591 @@
+#![cfg(feature = "integration")]
+
+use sunbeam_sdk::client::{AuthMethod, HttpTransport, SunbeamClient};
+use sunbeam_sdk::config::Context;
+use wiremock::matchers::{header, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use reqwest::Method;
+
+// ---------------------------------------------------------------------------
+// 1. json() success — 200 + valid JSON
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn json_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/api/things"))
+        .respond_with(
+            ResponseTemplate::new(200)
+                .set_body_json(serde_json::json!({"id": 42, "name": "widget"})),
+        )
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let val: serde_json::Value = t
+        .json(Method::GET, "/api/things", Option::<&()>::None, "fetch things")
+        .await
+        .unwrap();
+
+    assert_eq!(val["id"], 42);
+    assert_eq!(val["name"], "widget");
+}
+
+// ---------------------------------------------------------------------------
+// 2. json() HTTP error — 500 returns SunbeamError::Network with ctx in msg
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn json_http_error() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/fail"))
+        .respond_with(ResponseTemplate::new(500).set_body_string("internal oops"))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let err = t
+        .json::<serde_json::Value>(Method::GET, "/fail", Option::<&()>::None, "load stuff")
+        .await
+        .unwrap_err();
+
+    let msg = err.to_string();
+    assert!(msg.contains("load stuff"), "error should contain ctx: {msg}");
+    assert!(msg.contains("500"), "error should contain status: {msg}");
+}
+
+// ---------------------------------------------------------------------------
+// 3. json() parse error — 200 + invalid JSON
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn json_parse_error() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/bad-json"))
+        .respond_with(ResponseTemplate::new(200).set_body_string("not json {{{"))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let err = t
+        .json::<serde_json::Value>(Method::GET, "/bad-json", Option::<&()>::None, "parse ctx")
+        .await
+        .unwrap_err();
+
+    let msg = err.to_string();
+    assert!(
+        msg.contains("parse ctx"),
+        "parse error should contain ctx: {msg}"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 4. json_opt() success — 200 + JSON → Some(T)
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn json_opt_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/item"))
+        .respond_with(
+            ResponseTemplate::new(200).set_body_json(serde_json::json!({"found": true})),
+        )
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let val: Option<serde_json::Value> = t
+        .json_opt(Method::GET, "/item", Option::<&()>::None, "get item")
+        .await
+        .unwrap();
+
+    assert!(val.is_some());
+    assert_eq!(val.unwrap()["found"], true);
+}
+
+// ---------------------------------------------------------------------------
+// 5. json_opt() 404 → None
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn json_opt_not_found() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/missing"))
+        .respond_with(ResponseTemplate::new(404))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let val: Option<serde_json::Value> = t
+        .json_opt(Method::GET, "/missing", Option::<&()>::None, "lookup")
+        .await
+        .unwrap();
+
+    assert!(val.is_none());
+}
+
+// ---------------------------------------------------------------------------
+// 6. json_opt() server error — 500 → Err
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn json_opt_server_error() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/boom"))
+        .respond_with(ResponseTemplate::new(500).set_body_string("boom"))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let err = t
+        .json_opt::<serde_json::Value>(Method::GET, "/boom", Option::<&()>::None, "opt-fail")
+        .await
+        .unwrap_err();
+
+    let msg = err.to_string();
+    assert!(msg.contains("opt-fail"), "error should contain ctx: {msg}");
+    assert!(msg.contains("500"), "error should contain status: {msg}");
+}
+
+// ---------------------------------------------------------------------------
+// 7. send() success — 200 → Ok(())
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn send_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/action"))
+        .respond_with(ResponseTemplate::new(200))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    t.send(Method::POST, "/action", Option::<&()>::None, "do action")
+        .await
+        .unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// 8. send() error — 403 → Err
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn send_forbidden() {
+    let server = MockServer::start().await;
+    Mock::given(method("DELETE"))
+        .and(path("/protected"))
+        .respond_with(ResponseTemplate::new(403).set_body_string("forbidden"))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let err = t
+        .send(Method::DELETE, "/protected", Option::<&()>::None, "delete thing")
+        .await
+        .unwrap_err();
+
+    let msg = err.to_string();
+    assert!(msg.contains("delete thing"), "error should contain ctx: {msg}");
+    assert!(msg.contains("403"), "error should contain status: {msg}");
+}
+
+// ---------------------------------------------------------------------------
+// 9. bytes() success — 200 + raw bytes
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn bytes_success() {
+    let payload = b"binary-data-here";
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/download"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(payload.to_vec()))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let data = t.bytes(Method::GET, "/download", "fetch binary").await.unwrap();
+
+    assert_eq!(data.as_ref(), payload);
+}
+
+// ---------------------------------------------------------------------------
+// 10. bytes() error — 500
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn bytes_error() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/download-fail"))
+        .respond_with(ResponseTemplate::new(500).set_body_string("nope"))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let err = t
+        .bytes(Method::GET, "/download-fail", "get bytes")
+        .await
+        .unwrap_err();
+
+    let msg = err.to_string();
+    assert!(msg.contains("get bytes"), "error should contain ctx: {msg}");
+    assert!(msg.contains("500"), "error should contain status: {msg}");
+}
+
+// ---------------------------------------------------------------------------
+// 11. request() with Bearer auth — verify Authorization header
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn request_bearer_auth() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/auth-check"))
+        .and(header("Authorization", "Bearer my-secret-token"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"ok": true})))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::Bearer("my-secret-token".into()));
+    let val: serde_json::Value = t
+        .json(Method::GET, "/auth-check", Option::<&()>::None, "bearer test")
+        .await
+        .unwrap();
+
+    assert_eq!(val["ok"], true);
+}
+
+// ---------------------------------------------------------------------------
+// 12. request() with Header auth — verify custom header
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn request_header_auth() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/vault"))
+        .and(header("X-Vault-Token", "hvs.root-token"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"sealed": false})))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(
+        &server.uri(),
+        AuthMethod::Header {
+            name: "X-Vault-Token",
+            value: "hvs.root-token".into(),
+        },
+    );
+    let val: serde_json::Value = t
+        .json(Method::GET, "/vault", Option::<&()>::None, "header auth")
+        .await
+        .unwrap();
+
+    assert_eq!(val["sealed"], false);
+}
+
+// ---------------------------------------------------------------------------
+// 13. request() with Token auth — verify "token {pat}" format
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn request_token_auth() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/gitea"))
+        .and(header("Authorization", "token pat-abc-123"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"user": "ci"})))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::Token("pat-abc-123".into()));
+    let val: serde_json::Value = t
+        .json(Method::GET, "/gitea", Option::<&()>::None, "token auth")
+        .await
+        .unwrap();
+
+    assert_eq!(val["user"], "ci");
+}
+
+// ---------------------------------------------------------------------------
+// 14. request() with None auth — no Authorization header
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn request_no_auth() {
+    let server = MockServer::start().await;
+
+    // The mock only matches when there is NO Authorization header.
+    // wiremock does not have a "header absent" matcher, so we just verify
+    // the request succeeds (no auth header is fine) and inspect received
+    // requests afterward.
+    Mock::given(method("GET"))
+        .and(path("/public"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"public": true})))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let val: serde_json::Value = t
+        .json(Method::GET, "/public", Option::<&()>::None, "no auth")
+        .await
+        .unwrap();
+
+    assert_eq!(val["public"], true);
+
+    // Verify no Authorization header was sent.
+    let reqs = server.received_requests().await.unwrap();
+    assert_eq!(reqs.len(), 1);
+    assert!(
+        !reqs[0].headers.iter().any(|(k, _)| k == "authorization"),
+        "Authorization header should not be present for AuthMethod::None"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 15. set_auth() — change auth, verify next request uses new auth
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn set_auth_changes_header() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/check"))
+        .and(header("Authorization", "Bearer new-tok"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"ok": true})))
+        .mount(&server)
+        .await;
+
+    let mut t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    t.set_auth(AuthMethod::Bearer("new-tok".into()));
+
+    let val: serde_json::Value = t
+        .json(Method::GET, "/check", Option::<&()>::None, "after set_auth")
+        .await
+        .unwrap();
+
+    assert_eq!(val["ok"], true);
+}
+
+// ---------------------------------------------------------------------------
+// 16. URL construction — leading slash handling
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn url_construction_with_leading_slash() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/a/b"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"p": "ok"})))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+
+    // With leading slash
+    let val: serde_json::Value = t
+        .json(Method::GET, "/a/b", Option::<&()>::None, "slash")
+        .await
+        .unwrap();
+    assert_eq!(val["p"], "ok");
+}
+
+#[tokio::test]
+async fn url_construction_without_leading_slash() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/x/y"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"q": 1})))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+
+    // Without leading slash
+    let val: serde_json::Value = t
+        .json(Method::GET, "x/y", Option::<&()>::None, "no-slash")
+        .await
+        .unwrap();
+    assert_eq!(val["q"], 1);
+}
+
+#[tokio::test]
+async fn url_construction_trailing_slash_stripped() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/z"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"z": true})))
+        .mount(&server)
+        .await;
+
+    // Base URL with trailing slash
+    let t = HttpTransport::new(&format!("{}/", server.uri()), AuthMethod::None);
+    let val: serde_json::Value = t
+        .json(Method::GET, "/z", Option::<&()>::None, "trailing")
+        .await
+        .unwrap();
+    assert_eq!(val["z"], true);
+}
+
+// ---------------------------------------------------------------------------
+// 17. SunbeamClient::from_context() — domain, context accessors
+// ---------------------------------------------------------------------------
+
+#[test]
+fn sunbeam_client_from_context() {
+    let ctx = Context {
+        domain: "test.sunbeam.dev".to_string(),
+        kube_context: "k3s-test".to_string(),
+        ssh_host: "root@10.0.0.1".to_string(),
+        infra_dir: "/opt/infra".to_string(),
+        acme_email: "ops@test.dev".to_string(),
+    };
+
+    let client = SunbeamClient::from_context(&ctx);
+
+    assert_eq!(client.domain(), "test.sunbeam.dev");
+    assert_eq!(client.context().domain, "test.sunbeam.dev");
+    assert_eq!(client.context().kube_context, "k3s-test");
+    assert_eq!(client.context().ssh_host, "root@10.0.0.1");
+    assert_eq!(client.context().infra_dir, "/opt/infra");
+    assert_eq!(client.context().acme_email, "ops@test.dev");
+}
+
+// ---------------------------------------------------------------------------
+// Extra: json() with a request body (covers the Some(b) branch)
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn json_with_request_body() {
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/create"))
+        .and(header("content-type", "application/json"))
+        .respond_with(
+            ResponseTemplate::new(201).set_body_json(serde_json::json!({"id": 99})),
+        )
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let body = serde_json::json!({"name": "new-thing"});
+    let val: serde_json::Value = t
+        .json(Method::POST, "/create", Some(&body), "create thing")
+        .await
+        .unwrap();
+
+    assert_eq!(val["id"], 99);
+}
+
+// ---------------------------------------------------------------------------
+// Extra: json_opt() with a request body
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn json_opt_with_request_body() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/update"))
+        .and(header("content-type", "application/json"))
+        .respond_with(
+            ResponseTemplate::new(200).set_body_json(serde_json::json!({"updated": true})),
+        )
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let body = serde_json::json!({"field": "value"});
+    let val: Option<serde_json::Value> = t
+        .json_opt(Method::PUT, "/update", Some(&body), "update thing")
+        .await
+        .unwrap();
+
+    assert!(val.is_some());
+    assert_eq!(val.unwrap()["updated"], true);
+}
+
+// ---------------------------------------------------------------------------
+// Extra: send() with a request body
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn send_with_request_body() {
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/submit"))
+        .and(header("content-type", "application/json"))
+        .respond_with(ResponseTemplate::new(204))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let body = serde_json::json!({"payload": 123});
+    t.send(Method::POST, "/submit", Some(&body), "submit data")
+        .await
+        .unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// Extra: json_opt() parse error — 200 + invalid JSON → Err
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn json_opt_parse_error() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/bad-opt"))
+        .respond_with(ResponseTemplate::new(200).set_body_string("<<<not json>>>"))
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let err = t
+        .json_opt::<serde_json::Value>(Method::GET, "/bad-opt", Option::<&()>::None, "opt-parse")
+        .await
+        .unwrap_err();
+
+    let msg = err.to_string();
+    assert!(
+        msg.contains("opt-parse"),
+        "parse error should contain ctx: {msg}"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Extra: error body text appears in Network error messages
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn error_body_text_in_message() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/err-body"))
+        .respond_with(
+            ResponseTemplate::new(422).set_body_string("validation failed: email required"),
+        )
+        .mount(&server)
+        .await;
+
+    let t = HttpTransport::new(&server.uri(), AuthMethod::None);
+    let err = t
+        .json::<serde_json::Value>(Method::GET, "/err-body", Option::<&()>::None, "validate")
+        .await
+        .unwrap_err();
+
+    let msg = err.to_string();
+    assert!(msg.contains("422"), "should contain status: {msg}");
+    assert!(
+        msg.contains("validation failed"),
+        "should contain body text: {msg}"
+    );
+}

sunbeam-sdk/tests/test_hydra.rs

@@ -0,0 +1,442 @@
+#![cfg(feature = "integration")]
+mod helpers;
+use helpers::*;
+use sunbeam_sdk::client::{AuthMethod, ServiceClient};
+use sunbeam_sdk::auth::hydra::HydraClient;
+use sunbeam_sdk::auth::hydra::types::*;
+
+const HYDRA_HEALTH: &str = "http://localhost:4445/health/alive";
+
+fn hydra() -> HydraClient {
+    HydraClient::from_parts("http://localhost:4445".into(), AuthMethod::None)
+}
+
+// ---------------------------------------------------------------------------
+// 1. OAuth2 Client CRUD
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn oauth2_client_crud() {
+    wait_for_healthy(HYDRA_HEALTH, TIMEOUT).await;
+    let h = hydra();
+    let name = unique_name("test-client");
+
+    // Create
+    let body = OAuth2Client {
+        client_name: Some(name.clone()),
+        redirect_uris: Some(vec!["http://localhost:9999/cb".into()]),
+        grant_types: Some(vec!["authorization_code".into(), "refresh_token".into()]),
+        response_types: Some(vec!["code".into()]),
+        scope: Some("openid offline".into()),
+        token_endpoint_auth_method: Some("client_secret_post".into()),
+        ..Default::default()
+    };
+    let created = h.create_client(&body).await.expect("create_client");
+    let cid = created.client_id.as_deref().expect("created client must have id");
+    assert_eq!(created.client_name.as_deref(), Some(name.as_str()));
+
+    // List — created client should appear
+    let list = h.list_clients(Some(100), Some(0)).await.expect("list_clients");
+    assert!(
+        list.iter().any(|c| c.client_id.as_deref() == Some(cid)),
+        "created client should appear in list"
+    );
+
+    // Get
+    let fetched = h.get_client(cid).await.expect("get_client");
+    assert_eq!(fetched.client_name.as_deref(), Some(name.as_str()));
+
+    // Update (PUT) — change name
+    let updated_name = format!("{name}-updated");
+    let update_body = OAuth2Client {
+        client_name: Some(updated_name.clone()),
+        redirect_uris: Some(vec!["http://localhost:9999/cb".into()]),
+        grant_types: Some(vec!["authorization_code".into()]),
+        response_types: Some(vec!["code".into()]),
+        scope: Some("openid".into()),
+        token_endpoint_auth_method: Some("client_secret_post".into()),
+        ..Default::default()
+    };
+    let updated = h.update_client(cid, &update_body).await.expect("update_client");
+    assert_eq!(updated.client_name.as_deref(), Some(updated_name.as_str()));
+
+    // Patch — change scope via JSON Patch
+    let patches = vec![serde_json::json!({
+        "op": "replace",
+        "path": "/scope",
+        "value": "openid offline profile"
+    })];
+    let patched = h.patch_client(cid, &patches).await.expect("patch_client");
+    assert_eq!(patched.scope.as_deref(), Some("openid offline profile"));
+
+    // Set lifespans
+    let lifespans = TokenLifespans {
+        authorization_code_grant_access_token_lifespan: Some("3600s".into()),
+        ..Default::default()
+    };
+    let with_lifespans = h
+        .set_client_lifespans(cid, &lifespans)
+        .await
+        .expect("set_client_lifespans");
+    assert!(with_lifespans.client_id.as_deref() == Some(cid));
+
+    // Delete
+    h.delete_client(cid).await.expect("delete_client");
+
+    // Verify deleted
+    let err = h.get_client(cid).await;
+    assert!(err.is_err(), "get_client after delete should fail");
+}
+
+// ---------------------------------------------------------------------------
+// 2. Token introspect
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn token_introspect() {
+    wait_for_healthy(HYDRA_HEALTH, TIMEOUT).await;
+    let h = hydra();
+
+    let result = h
+        .introspect_token("totally-bogus-token-that-does-not-exist")
+        .await
+        .expect("introspect should not error for bogus token");
+    assert!(!result.active, "bogus token must be inactive");
+}
+
+// ---------------------------------------------------------------------------
+// 3. Delete tokens for client
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn delete_tokens_for_client() {
+    wait_for_healthy(HYDRA_HEALTH, TIMEOUT).await;
+    let h = hydra();
+
+    // Create a throwaway client
+    let body = OAuth2Client {
+        client_name: Some(unique_name("tok-del")),
+        grant_types: Some(vec!["client_credentials".into()]),
+        response_types: Some(vec!["token".into()]),
+        scope: Some("openid".into()),
+        token_endpoint_auth_method: Some("client_secret_post".into()),
+        ..Default::default()
+    };
+    let created = h.create_client(&body).await.expect("create client for token delete");
+    let cid = created.client_id.as_deref().expect("client id");
+
+    // Delete tokens — should succeed (no-op, no tokens issued yet)
+    h.delete_tokens_for_client(cid)
+        .await
+        .expect("delete_tokens_for_client should not error");
+
+    // Cleanup
+    h.delete_client(cid).await.expect("cleanup client");
+}
+
+// ---------------------------------------------------------------------------
+// 4. JWK set CRUD
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn jwk_set_crud() {
+    wait_for_healthy(HYDRA_HEALTH, TIMEOUT).await;
+    let h = hydra();
+    let set_name = unique_name("test-jwk-set");
+
+    // Create
+    let create_body = CreateJwkBody {
+        alg: "RS256".into(),
+        kid: format!("{set_name}-key"),
+        use_: "sig".into(),
+    };
+    let created = h
+        .create_jwk_set(&set_name, &create_body)
+        .await
+        .expect("create_jwk_set");
+    assert!(!created.keys.is_empty(), "created set should have at least one key");
+
+    // Get
+    let fetched = h.get_jwk_set(&set_name).await.expect("get_jwk_set");
+    assert!(!fetched.keys.is_empty());
+
+    // Update — replace the set with the same keys (idempotent)
+    let update_body = JwkSet {
+        keys: fetched.keys.clone(),
+    };
+    let updated = h
+        .update_jwk_set(&set_name, &update_body)
+        .await
+        .expect("update_jwk_set");
+    assert_eq!(updated.keys.len(), fetched.keys.len());
+
+    // Delete
+    h.delete_jwk_set(&set_name).await.expect("delete_jwk_set");
+
+    // Verify deleted
+    let err = h.get_jwk_set(&set_name).await;
+    assert!(err.is_err(), "get_jwk_set after delete should fail");
+}
+
+// ---------------------------------------------------------------------------
+// 5. JWK key CRUD (within a set)
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn jwk_key_crud() {
+    wait_for_healthy(HYDRA_HEALTH, TIMEOUT).await;
+    let h = hydra();
+    let set_name = unique_name("test-jwk-key");
+
+    // Create a set first
+    let kid = format!("{set_name}-k1");
+    let create_body = CreateJwkBody {
+        alg: "RS256".into(),
+        kid: kid.clone(),
+        use_: "sig".into(),
+    };
+    let created = h
+        .create_jwk_set(&set_name, &create_body)
+        .await
+        .expect("create_jwk_set for key test");
+
+    // The kid Hydra assigns may differ from what we requested; extract it.
+    let actual_kid = created.keys[0]["kid"]
+        .as_str()
+        .expect("key must have kid")
+        .to_string();
+
+    // Get single key
+    let key_set = h
+        .get_jwk_key(&set_name, &actual_kid)
+        .await
+        .expect("get_jwk_key");
+    assert_eq!(key_set.keys.len(), 1);
+
+    // Update single key — send the same key back
+    let key_val = key_set.keys[0].clone();
+    let updated = h
+        .update_jwk_key(&set_name, &actual_kid, &key_val)
+        .await
+        .expect("update_jwk_key");
+    assert!(updated.is_object());
+
+    // Delete single key
+    h.delete_jwk_key(&set_name, &actual_kid)
+        .await
+        .expect("delete_jwk_key");
+
+    // Cleanup — delete the (now empty) set; ignore error if already gone
+    let _ = h.delete_jwk_set(&set_name).await;
+}
+
+// ---------------------------------------------------------------------------
+// 6. Trusted JWT issuers
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn trusted_issuers() {
+    wait_for_healthy(HYDRA_HEALTH, TIMEOUT).await;
+    let h = hydra();
+
+    // We need a JWK set for the issuer to reference
+    let set_name = unique_name("trust-jwk");
+    let kid = format!("{set_name}-k");
+    let jwk_body = CreateJwkBody {
+        alg: "RS256".into(),
+        kid: kid.clone(),
+        use_: "sig".into(),
+    };
+    let jwk_set = h
+        .create_jwk_set(&set_name, &jwk_body)
+        .await
+        .expect("create jwk set for trusted issuer");
+    let actual_kid = jwk_set.keys[0]["kid"]
+        .as_str()
+        .expect("kid")
+        .to_string();
+
+    // Create trusted issuer
+    let issuer_body = TrustedJwtIssuer {
+        id: None,
+        issuer: format!("https://{}.example.com", unique_name("iss")),
+        subject: "test-subject".into(),
+        scope: vec!["openid".into()],
+        public_key: Some(TrustedIssuerKey {
+            set: Some(set_name.clone()),
+            kid: Some(actual_kid.clone()),
+        }),
+        expires_at: Some("2099-12-31T23:59:59Z".into()),
+        created_at: None,
+    };
+    let created = match h.create_trusted_issuer(&issuer_body).await {
+        Ok(c) => c,
+        Err(_) => {
+            // Hydra may require inline JWK — skip if not supported
+            let _ = h.delete_jwk_set(&set_name).await;
+            return;
+        }
+    };
+    let issuer_id = created.id.as_deref().expect("trusted issuer must have id");
+
+    // List
+    let list = h.list_trusted_issuers().await.expect("list_trusted_issuers");
+    assert!(
+        list.iter().any(|i| i.id.as_deref() == Some(issuer_id)),
+        "created issuer should appear in list"
+    );
+
+    // Get
+    let fetched = h
+        .get_trusted_issuer(issuer_id)
+        .await
+        .expect("get_trusted_issuer");
+    assert_eq!(fetched.issuer, created.issuer);
+
+    // Delete
+    h.delete_trusted_issuer(issuer_id)
+        .await
+        .expect("delete_trusted_issuer");
+
+    // Verify deleted
+    let err = h.get_trusted_issuer(issuer_id).await;
+    assert!(err.is_err(), "get after delete should fail");
+
+    // Cleanup JWK set
+    let _ = h.delete_jwk_set(&set_name).await;
+}
+
+// ---------------------------------------------------------------------------
+// 7. Consent sessions
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn consent_sessions() {
+    wait_for_healthy(HYDRA_HEALTH, TIMEOUT).await;
+    let h = hydra();
+
+    let subject = unique_name("nonexistent-user");
+
+    // List consent sessions for a subject that has none — expect empty list
+    let sessions = h
+        .list_consent_sessions(&subject)
+        .await
+        .expect("list_consent_sessions");
+    assert!(sessions.is_empty(), "non-existent subject should have no sessions");
+
+    // Revoke consent sessions with a client filter (Hydra requires either client or all=true)
+    let _ = h.revoke_consent_sessions(&subject, Some("no-such-client")).await;
+
+    // Revoke login sessions
+    let _ = h.revoke_login_sessions(&subject).await;
+}
+
+// ---------------------------------------------------------------------------
+// 8. Login flow — bogus challenge
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn login_flow() {
+    wait_for_healthy(HYDRA_HEALTH, TIMEOUT).await;
+    let h = hydra();
+
+    let bogus = "bogus-login-challenge-12345";
+
+    // get_login_request with invalid challenge should error, not panic
+    let err = h.get_login_request(bogus).await;
+    assert!(err.is_err(), "get_login_request with bogus challenge should error");
+
+    // accept_login with invalid challenge should error, not panic
+    let accept_body = AcceptLoginBody {
+        subject: "test".into(),
+        remember: None,
+        remember_for: None,
+        acr: None,
+        amr: None,
+        context: None,
+        force_subject_identifier: None,
+    };
+    let err = h.accept_login(bogus, &accept_body).await;
+    assert!(err.is_err(), "accept_login with bogus challenge should error");
+
+    // reject_login with invalid challenge should error, not panic
+    let reject_body = RejectBody {
+        error: Some("access_denied".into()),
+        error_description: Some("test".into()),
+        error_debug: None,
+        error_hint: None,
+        status_code: Some(403),
+    };
+    let err = h.reject_login(bogus, &reject_body).await;
+    assert!(err.is_err(), "reject_login with bogus challenge should error");
+}
+
+// ---------------------------------------------------------------------------
+// 9. Consent flow — bogus challenge
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn consent_flow() {
+    wait_for_healthy(HYDRA_HEALTH, TIMEOUT).await;
+    let h = hydra();
+
+    let bogus = "bogus-consent-challenge-12345";
+
+    // get_consent_request
+    let err = h.get_consent_request(bogus).await;
+    assert!(err.is_err(), "get_consent_request with bogus challenge should error");
+
+    // accept_consent
+    let accept_body = AcceptConsentBody {
+        grant_scope: Some(vec!["openid".into()]),
+        grant_access_token_audience: None,
+        session: None,
+        remember: None,
+        remember_for: None,
+        handled_at: None,
+    };
+    let err = h.accept_consent(bogus, &accept_body).await;
+    assert!(err.is_err(), "accept_consent with bogus challenge should error");
+
+    // reject_consent
+    let reject_body = RejectBody {
+        error: Some("access_denied".into()),
+        error_description: Some("test".into()),
+        error_debug: None,
+        error_hint: None,
+        status_code: Some(403),
+    };
+    let err = h.reject_consent(bogus, &reject_body).await;
+    assert!(err.is_err(), "reject_consent with bogus challenge should error");
+}
+
+// ---------------------------------------------------------------------------
+// 10. Logout flow — bogus challenge
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn logout_flow() {
+    wait_for_healthy(HYDRA_HEALTH, TIMEOUT).await;
+    let h = hydra();
+
+    let bogus = "bogus-logout-challenge-12345";
+
+    // get_logout_request
+    let err = h.get_logout_request(bogus).await;
+    assert!(err.is_err(), "get_logout_request with bogus challenge should error");
+
+    // accept_logout
+    let err = h.accept_logout(bogus).await;
+    assert!(err.is_err(), "accept_logout with bogus challenge should error");
+
+    // reject_logout
+    let reject_body = RejectBody {
+        error: Some("access_denied".into()),
+        error_description: Some("test".into()),
+        error_debug: None,
+        error_hint: None,
+        status_code: Some(403),
+    };
+    let err = h.reject_logout(bogus, &reject_body).await;
+    assert!(err.is_err(), "reject_logout with bogus challenge should error");
+}

sunbeam-sdk/tests/test_kratos.rs

@@ -0,0 +1,667 @@
+#![cfg(feature = "integration")]
+mod helpers;
+use helpers::*;
+use sunbeam_sdk::client::{AuthMethod, ServiceClient};
+use sunbeam_sdk::identity::KratosClient;
+use sunbeam_sdk::identity::types::*;
+
+const KRATOS_URL: &str = "http://localhost:4434";
+const HEALTH_URL: &str = "http://localhost:4434/health/alive";
+
+fn kratos_client() -> KratosClient {
+    KratosClient::from_parts(KRATOS_URL.into(), AuthMethod::None)
+}
+
+fn make_create_body(email: &str) -> CreateIdentityBody {
+    CreateIdentityBody {
+        schema_id: "default".into(),
+        traits: serde_json::json!({ "email": email }),
+        state: Some("active".into()),
+        metadata_public: None,
+        metadata_admin: None,
+        credentials: None,
+        verifiable_addresses: None,
+        recovery_addresses: None,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// 1. Health
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn health() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    let alive = client.alive().await.expect("alive failed");
+    assert_eq!(alive.status, "ok");
+
+    let ready = client.ready().await.expect("ready failed");
+    assert_eq!(ready.status, "ok");
+}
+
+// ---------------------------------------------------------------------------
+// 2. Identity CRUD
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn identity_crud() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+    let email = format!("{}@test.local", unique_name("crud"));
+
+    // Create
+    let created = client
+        .create_identity(&make_create_body(&email))
+        .await
+        .expect("create_identity failed");
+    assert_eq!(created.schema_id, "default");
+    assert_eq!(created.traits["email"], email);
+    let id = created.id.clone();
+
+    // Get
+    let fetched = client.get_identity(&id).await.expect("get_identity failed");
+    assert_eq!(fetched.id, id);
+    assert_eq!(fetched.traits["email"], email);
+
+    // List (should contain our identity)
+    let list = client
+        .list_identities(Some(1), Some(100))
+        .await
+        .expect("list_identities failed");
+    assert!(
+        list.iter().any(|i| i.id == id),
+        "created identity not found in list"
+    );
+
+    // Update (full replace)
+    let new_email = format!("{}@test.local", unique_name("updated"));
+    let update_body = UpdateIdentityBody {
+        schema_id: "default".into(),
+        traits: serde_json::json!({ "email": new_email }),
+        state: "active".into(),
+        metadata_public: None,
+        metadata_admin: None,
+        credentials: None,
+    };
+    let updated = client
+        .update_identity(&id, &update_body)
+        .await
+        .expect("update_identity failed");
+    assert_eq!(updated.traits["email"], new_email);
+
+    // Patch (partial update via JSON Patch)
+    let patch_email = format!("{}@test.local", unique_name("patched"));
+    let patches = vec![serde_json::json!({
+        "op": "replace",
+        "path": "/traits/email",
+        "value": patch_email,
+    })];
+    let patched = client
+        .patch_identity(&id, &patches)
+        .await
+        .expect("patch_identity failed");
+    assert_eq!(patched.traits["email"], patch_email);
+
+    // Delete
+    client
+        .delete_identity(&id)
+        .await
+        .expect("delete_identity failed");
+
+    // Confirm deletion
+    let err = client.get_identity(&id).await;
+    assert!(err.is_err(), "expected 404 after deletion");
+}
+
+// ---------------------------------------------------------------------------
+// 3. Identity by credential identifier
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn identity_by_credential() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+    let email = format!("{}@test.local", unique_name("cred"));
+
+    let created = client
+        .create_identity(&make_create_body(&email))
+        .await
+        .expect("create failed");
+    let id = created.id.clone();
+
+    let results = client
+        .get_by_credential_identifier(&email)
+        .await
+        .expect("get_by_credential_identifier failed");
+    assert!(
+        results.iter().any(|i| i.id == id),
+        "identity not found by credential identifier"
+    );
+
+    // Cleanup
+    client.delete_identity(&id).await.expect("cleanup failed");
+}
+
+// ---------------------------------------------------------------------------
+// 4. Delete credential (OIDC — may 404, which is fine)
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn identity_delete_credential() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+    let email = format!("{}@test.local", unique_name("delcred"));
+
+    let created = client
+        .create_identity(&make_create_body(&email))
+        .await
+        .expect("create failed");
+    let id = created.id.clone();
+
+    // Attempt to delete an OIDC credential — the identity has none, so a 404
+    // or similar error is acceptable.
+    let result = client.delete_credential(&id, "oidc").await;
+    // We don't assert success; a 404 is the expected outcome for identities
+    // without OIDC credentials.
+    if let Err(ref e) = result {
+        let msg = format!("{e}");
+        assert!(
+            msg.contains("404") || msg.contains("Not Found") || msg.contains("does not have"),
+            "unexpected error: {msg}"
+        );
+    }
+
+    // Cleanup
+    client.delete_identity(&id).await.expect("cleanup failed");
+}
+
+// ---------------------------------------------------------------------------
+// 5. Batch patch identities
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn batch_patch() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    let email_a = format!("{}@test.local", unique_name("batch-a"));
+    let email_b = format!("{}@test.local", unique_name("batch-b"));
+
+    let body = BatchPatchIdentitiesBody {
+        identities: vec![
+            BatchPatchEntry {
+                create: Some(make_create_body(&email_a)),
+                patch_id: Some("00000000-0000-0000-0000-000000000001".into()),
+            },
+            BatchPatchEntry {
+                create: Some(make_create_body(&email_b)),
+                patch_id: Some("00000000-0000-0000-0000-000000000002".into()),
+            },
+        ],
+    };
+
+    let result = client
+        .batch_patch_identities(&body)
+        .await
+        .expect("batch_patch_identities failed");
+    assert_eq!(result.identities.len(), 2, "expected 2 results");
+
+    // Cleanup created identities
+    for entry in &result.identities {
+        if let Some(ref identity_id) = entry.identity {
+            let _ = client.delete_identity(identity_id).await;
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// 6. Sessions (global list — may be empty)
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn sessions() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    // Create an identity so at least the endpoint is exercised.
+    let email = format!("{}@test.local", unique_name("sess"));
+    let created = client
+        .create_identity(&make_create_body(&email))
+        .await
+        .expect("create failed");
+
+    let sessions = client
+        .list_sessions(Some(10), None, None)
+        .await
+        .expect("list_sessions failed");
+    // An empty list is acceptable — no sessions exist until a login flow runs.
+    assert!(sessions.len() <= 10);
+
+    // Cleanup
+    client
+        .delete_identity(&created.id)
+        .await
+        .expect("cleanup failed");
+}
+
+// ---------------------------------------------------------------------------
+// 7. Identity sessions
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn identity_sessions() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    let email = format!("{}@test.local", unique_name("idsess"));
+    let created = client
+        .create_identity(&make_create_body(&email))
+        .await
+        .expect("create failed");
+    let id = created.id.clone();
+
+    // List sessions for this identity — expect empty.
+    let sessions = client
+        .list_identity_sessions(&id)
+        .await;
+    // Kratos may return 404 when there are no sessions, or an empty list.
+    match sessions {
+        Ok(list) => assert!(list.is_empty(), "expected no sessions for new identity"),
+        Err(ref e) => {
+            let msg = format!("{e}");
+            assert!(
+                msg.contains("404") || msg.contains("Not Found"),
+                "unexpected error listing identity sessions: {msg}"
+            );
+        }
+    }
+
+    // Delete sessions for this identity (no-op if none exist, may 404).
+    let del = client.delete_identity_sessions(&id).await;
+    if let Err(ref e) = del {
+        let msg = format!("{e}");
+        assert!(
+            msg.contains("404") || msg.contains("Not Found"),
+            "unexpected error deleting identity sessions: {msg}"
+        );
+    }
+
+    // Cleanup
+    client.delete_identity(&id).await.expect("cleanup failed");
+}
+
+// ---------------------------------------------------------------------------
+// 8. Recovery (code + link)
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn recovery() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    let email = format!("{}@test.local", unique_name("recov"));
+    let created = client
+        .create_identity(&make_create_body(&email))
+        .await
+        .expect("create failed");
+    let id = created.id.clone();
+
+    // Recovery code
+    let code_result = client
+        .create_recovery_code(&id, Some("1h"))
+        .await
+        .expect("create_recovery_code failed");
+    assert!(
+        !code_result.recovery_link.is_empty(),
+        "recovery_link should not be empty"
+    );
+    assert!(
+        !code_result.recovery_code.is_empty(),
+        "recovery_code should not be empty"
+    );
+
+    // Recovery link (may be disabled in dev mode — handle gracefully)
+    match client.create_recovery_link(&id, Some("1h")).await {
+        Ok(link_result) => {
+            assert!(!link_result.recovery_link.is_empty());
+        }
+        Err(_) => {
+            // Endpoint disabled in dev mode — acceptable
+        }
+    }
+
+    // Cleanup
+    client.delete_identity(&id).await.expect("cleanup failed");
+}
+
+// ---------------------------------------------------------------------------
+// 9. Schemas
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn schemas() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    // List schemas
+    let schemas = client.list_schemas().await.expect("list_schemas failed");
+    assert!(!schemas.is_empty(), "expected at least one schema");
+    assert!(
+        schemas.iter().any(|s| s.id == "default"),
+        "expected a 'default' schema in the list"
+    );
+
+    // Get specific schema
+    let schema = client
+        .get_schema("default")
+        .await
+        .expect("get_schema(\"default\") failed");
+    // The schema is a JSON Schema document; verify it has basic structure.
+    assert!(
+        schema.get("properties").is_some() || schema.get("type").is_some(),
+        "schema JSON should contain 'properties' or 'type'"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 10. Courier messages
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn courier() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    // List courier messages (may be empty).
+    let messages = client
+        .list_courier_messages(Some(10), None)
+        .await
+        .expect("list_courier_messages failed");
+
+    // If there are messages, fetch the first one by ID.
+    if let Some(first) = messages.first() {
+        let msg = client
+            .get_courier_message(&first.id)
+            .await
+            .expect("get_courier_message failed");
+        assert_eq!(msg.id, first.id);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// 11. Get identity — nonexistent ID
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn get_identity_nonexistent() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    let result = client
+        .get_identity("00000000-0000-0000-0000-000000000000")
+        .await;
+    assert!(result.is_err(), "expected error for nonexistent identity");
+}
+
+// ---------------------------------------------------------------------------
+// 12. Extend session — nonexistent session
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn extend_session_nonexistent() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    // Extending a session that doesn't exist should fail
+    let result = client
+        .extend_session("00000000-0000-0000-0000-000000000000")
+        .await;
+    assert!(result.is_err(), "expected error for nonexistent session");
+}
+
+// ---------------------------------------------------------------------------
+// 13. Disable session — nonexistent session
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn disable_session_nonexistent() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    let result = client
+        .disable_session("00000000-0000-0000-0000-000000000000")
+        .await;
+    // Kratos may return 404 or similar for nonexistent sessions
+    assert!(result.is_err(), "expected error for nonexistent session");
+}
+
+// ---------------------------------------------------------------------------
+// 14. Get session — nonexistent session
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn get_session_nonexistent() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    let result = client
+        .get_session("00000000-0000-0000-0000-000000000000")
+        .await;
+    assert!(result.is_err(), "expected error for nonexistent session");
+}
+
+// ---------------------------------------------------------------------------
+// 15. List sessions with active filter
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn list_sessions_active_filter() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    // List sessions filtering by active=true
+    let sessions = client
+        .list_sessions(Some(10), None, Some(true))
+        .await
+        .expect("list_sessions with active=true failed");
+    assert!(sessions.len() <= 10);
+
+    // List sessions filtering by active=false
+    let inactive = client
+        .list_sessions(Some(10), None, Some(false))
+        .await
+        .expect("list_sessions with active=false failed");
+    assert!(inactive.len() <= 10);
+}
+
+// ---------------------------------------------------------------------------
+// 16. Patch identity — add metadata
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn patch_identity_metadata() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+    let email = format!("{}@test.local", unique_name("patchmeta"));
+
+    let created = client
+        .create_identity(&make_create_body(&email))
+        .await
+        .expect("create failed");
+    let id = created.id.clone();
+
+    // Patch: add metadata_public
+    let patches = vec![serde_json::json!({
+        "op": "add",
+        "path": "/metadata_public",
+        "value": { "role": "admin" },
+    })];
+    let patched = client
+        .patch_identity(&id, &patches)
+        .await
+        .expect("patch_identity with metadata failed");
+    assert_eq!(patched.metadata_public.as_ref().unwrap()["role"], "admin");
+
+    // Cleanup
+    client.delete_identity(&id).await.expect("cleanup failed");
+}
+
+// ---------------------------------------------------------------------------
+// 17. List identities with default pagination
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn list_identities_defaults() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    // Use None for both params to exercise default path
+    let list = client
+        .list_identities(None, None)
+        .await
+        .expect("list_identities with defaults failed");
+    // Just verify it returns a valid vec
+    let _ = list;
+}
+
+// ---------------------------------------------------------------------------
+// 18. Recovery code with default expiry
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn recovery_code_default_expiry() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+    let email = format!("{}@test.local", unique_name("recovdef"));
+
+    let created = client
+        .create_identity(&make_create_body(&email))
+        .await
+        .expect("create failed");
+    let id = created.id.clone();
+
+    // Recovery code with None expiry (exercises default path)
+    let code_result = client
+        .create_recovery_code(&id, None)
+        .await
+        .expect("create_recovery_code with default expiry failed");
+    assert!(!code_result.recovery_link.is_empty());
+    assert!(!code_result.recovery_code.is_empty());
+
+    // Cleanup
+    client.delete_identity(&id).await.expect("cleanup failed");
+}
+
+// ---------------------------------------------------------------------------
+// 19. Get courier message — nonexistent
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn get_courier_message_nonexistent() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    let result = client
+        .get_courier_message("00000000-0000-0000-0000-000000000000")
+        .await;
+    assert!(result.is_err(), "expected error for nonexistent courier message");
+}
+
+// ---------------------------------------------------------------------------
+// 20. Get schema — nonexistent
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn get_schema_nonexistent() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    let result = client.get_schema("nonexistent-schema-zzz").await;
+    assert!(result.is_err(), "expected error for nonexistent schema");
+}
+
+// ---------------------------------------------------------------------------
+// 21. Patch identity — nonexistent ID
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn patch_identity_nonexistent() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    let patches = vec![serde_json::json!({
+        "op": "replace",
+        "path": "/traits/email",
+        "value": "gone@test.local",
+    })];
+    let result = client
+        .patch_identity("00000000-0000-0000-0000-000000000000", &patches)
+        .await;
+    assert!(result.is_err(), "expected error for nonexistent identity");
+}
+
+// ---------------------------------------------------------------------------
+// 22. Delete identity — nonexistent
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn delete_identity_nonexistent() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    let result = client
+        .delete_identity("00000000-0000-0000-0000-000000000000")
+        .await;
+    assert!(result.is_err(), "expected error for nonexistent identity");
+}
+
+// ---------------------------------------------------------------------------
+// 23. Update identity — nonexistent
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn update_identity_nonexistent() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    let update_body = UpdateIdentityBody {
+        schema_id: "default".into(),
+        traits: serde_json::json!({ "email": "gone@test.local" }),
+        state: "active".into(),
+        metadata_public: None,
+        metadata_admin: None,
+        credentials: None,
+    };
+    let result = client
+        .update_identity("00000000-0000-0000-0000-000000000000", &update_body)
+        .await;
+    assert!(result.is_err(), "expected error for nonexistent identity");
+}
+
+// ---------------------------------------------------------------------------
+// 24. List courier messages with page_token
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn list_courier_messages_with_token() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = kratos_client();
+
+    // List with a page_token — Kratos expects base64 encoded tokens.
+    // Use an invalid token to exercise the code path; expect an error.
+    let result = client.list_courier_messages(Some(5), Some("invalid-token")).await;
+    assert!(result.is_err(), "invalid page_token should produce an error");
+}
+
+// ---------------------------------------------------------------------------
+// 25. Connect constructor
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn connect_constructor() {
+    let client = KratosClient::connect("example.com");
+    assert_eq!(client.base_url(), "https://id.example.com");
+    assert_eq!(client.service_name(), "kratos");
+}

sunbeam-sdk/tests/test_livekit.rs

@@ -0,0 +1,350 @@
+#![cfg(feature = "integration")]
+mod helpers;
+use helpers::*;
+use sunbeam_sdk::client::{AuthMethod, ServiceClient};
+use sunbeam_sdk::media::LiveKitClient;
+use sunbeam_sdk::media::types::*;
+
+const LIVEKIT_URL: &str = "http://localhost:7880";
+const API_KEY: &str = "devkey";
+const API_SECRET: &str = "devsecret";
+
+fn livekit() -> LiveKitClient {
+    LiveKitClient::from_parts(
+        LIVEKIT_URL.into(),
+        AuthMethod::Bearer(livekit_test_token()),
+    )
+}
+
+// ---------------------------------------------------------------------------
+// 1. Token generation
+// ---------------------------------------------------------------------------
+
+#[test]
+fn token_generation_basic() {
+    let grants = VideoGrants {
+        room_join: Some(true),
+        room: Some("my-room".into()),
+        can_publish: Some(true),
+        can_subscribe: Some(true),
+        ..Default::default()
+    };
+    let token = LiveKitClient::generate_access_token(API_KEY, API_SECRET, "user-1", &grants, 3600)
+        .expect("generate_access_token");
+
+    // JWT has three dot-separated segments
+    let parts: Vec<&str> = token.split('.').collect();
+    assert_eq!(parts.len(), 3, "JWT must have 3 segments");
+    assert!(!parts[0].is_empty(), "header must not be empty");
+    assert!(!parts[1].is_empty(), "claims must not be empty");
+    assert!(!parts[2].is_empty(), "signature must not be empty");
+}
+
+#[test]
+fn token_generation_empty_grants() {
+    let grants = VideoGrants::default();
+    let token = LiveKitClient::generate_access_token(API_KEY, API_SECRET, "empty-grants", &grants, 600)
+        .expect("empty grants should still generate a token");
+
+    let parts: Vec<&str> = token.split('.').collect();
+    assert_eq!(parts.len(), 3);
+}
+
+#[test]
+fn token_generation_different_grants_produce_different_tokens() {
+    let grants_a = VideoGrants {
+        room_create: Some(true),
+        ..Default::default()
+    };
+    let grants_b = VideoGrants {
+        room_join: Some(true),
+        room: Some("specific-room".into()),
+        can_publish: Some(true),
+        ..Default::default()
+    };
+
+    let token_a = LiveKitClient::generate_access_token(API_KEY, API_SECRET, "user-a", &grants_a, 600)
+        .expect("token_a");
+    let token_b = LiveKitClient::generate_access_token(API_KEY, API_SECRET, "user-b", &grants_b, 600)
+        .expect("token_b");
+
+    assert_ne!(token_a, token_b, "different grants/identities must produce different tokens");
+}
+
+// ---------------------------------------------------------------------------
+// 2. Room CRUD
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn room_crud() {
+    wait_for_healthy(LIVEKIT_URL, TIMEOUT).await;
+    let lk = livekit();
+    let room_name = unique_name("test-room");
+
+    // Create
+    let room = lk
+        .create_room(&serde_json::json!({ "name": &room_name }))
+        .await
+        .expect("create_room");
+    assert_eq!(room.name, room_name);
+    assert!(!room.sid.is_empty(), "room must have a sid");
+
+    // List — our room should appear
+    let list = lk.list_rooms().await.expect("list_rooms");
+    assert!(
+        list.rooms.iter().any(|r| r.name == room_name),
+        "created room should appear in list_rooms"
+    );
+
+    // Update metadata (may require roomAdmin grant — handle gracefully)
+    match lk
+        .update_room_metadata(&serde_json::json!({
+            "room": &room_name,
+            "metadata": "hello-integration-test"
+        }))
+        .await
+    {
+        Ok(updated) => {
+            assert_eq!(updated.metadata.as_deref(), Some("hello-integration-test"));
+        }
+        Err(_) => {
+            // roomAdmin grant not available in test token — acceptable
+        }
+    }
+
+    // Delete
+    lk.delete_room(&serde_json::json!({ "room": &room_name }))
+        .await
+        .expect("delete_room");
+
+    // Verify deletion
+    let list_after = lk.list_rooms().await.expect("list_rooms after delete");
+    assert!(
+        !list_after.rooms.iter().any(|r| r.name == room_name),
+        "deleted room should no longer appear"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 3. Send data
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn send_data_to_room() {
+    wait_for_healthy(LIVEKIT_URL, TIMEOUT).await;
+    let lk = livekit();
+    let room_name = unique_name("test-room");
+
+    // Create room first
+    lk.create_room(&serde_json::json!({ "name": &room_name }))
+        .await
+        .expect("create_room for send_data");
+
+    // Send data — may succeed (no-op with no participants) or error; either is acceptable
+    let result = lk
+        .send_data(&serde_json::json!({
+            "room": &room_name,
+            "data": "aGVsbG8=",
+            "kind": 0
+        }))
+        .await;
+
+    // We don't require success — just ensure we don't panic.
+    // Some LiveKit versions silently accept, others return an error.
+    match &result {
+        Ok(()) => {} // fine
+        Err(e) => {
+            let msg = format!("{e}");
+            // Acceptable errors involve missing participants or similar
+            assert!(
+                !msg.is_empty(),
+                "error message should be non-empty"
+            );
+        }
+    }
+
+    // Cleanup
+    let _ = lk.delete_room(&serde_json::json!({ "room": &room_name })).await;
+}
+
+// ---------------------------------------------------------------------------
+// 4. Participants
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn list_participants_empty_room() {
+    wait_for_healthy(LIVEKIT_URL, TIMEOUT).await;
+    let lk = livekit();
+    let room_name = unique_name("test-room");
+
+    lk.create_room(&serde_json::json!({ "name": &room_name }))
+        .await
+        .expect("create_room for list_participants");
+
+    // No participants have joined — list should be empty
+    // LiveKit dev mode may reject this with 401 if roomAdmin grant isn't sufficient
+    match lk.list_participants(&serde_json::json!({ "room": &room_name })).await {
+        Ok(resp) => assert!(resp.participants.is_empty(), "room should have no participants"),
+        Err(e) => {
+            let msg = e.to_string();
+            assert!(
+                msg.contains("401") || msg.contains("unauthenticated"),
+                "unexpected error (expected 401 auth issue): {e}"
+            );
+        }
+    }
+
+    // Cleanup
+    let _ = lk.delete_room(&serde_json::json!({ "room": &room_name })).await;
+}
+
+#[tokio::test]
+async fn get_participant_not_found() {
+    wait_for_healthy(LIVEKIT_URL, TIMEOUT).await;
+    let lk = livekit();
+    let room_name = unique_name("test-room");
+
+    lk.create_room(&serde_json::json!({ "name": &room_name }))
+        .await
+        .expect("create_room for get_participant");
+
+    // Non-existent participant — should error
+    let result = lk
+        .get_participant(&serde_json::json!({
+            "room": &room_name,
+            "identity": "ghost-user"
+        }))
+        .await;
+
+    assert!(result.is_err(), "get_participant for non-existent identity should fail");
+    let err_msg = format!("{}", result.unwrap_err());
+    assert!(!err_msg.is_empty(), "error message should be non-empty");
+
+    // Cleanup
+    let _ = lk.delete_room(&serde_json::json!({ "room": &room_name })).await;
+}
+
+// ---------------------------------------------------------------------------
+// 5. Remove participant
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn remove_participant_not_found() {
+    wait_for_healthy(LIVEKIT_URL, TIMEOUT).await;
+    let lk = livekit();
+    let room_name = unique_name("test-room");
+
+    lk.create_room(&serde_json::json!({ "name": &room_name }))
+        .await
+        .expect("create_room for remove_participant");
+
+    let result = lk
+        .remove_participant(&serde_json::json!({
+            "room": &room_name,
+            "identity": "ghost-user"
+        }))
+        .await;
+
+    assert!(result.is_err(), "removing non-existent participant should fail");
+    let err_msg = format!("{}", result.unwrap_err());
+    assert!(!err_msg.is_empty(), "error message should describe the issue");
+
+    // Cleanup
+    let _ = lk.delete_room(&serde_json::json!({ "room": &room_name })).await;
+}
+
+// ---------------------------------------------------------------------------
+// 6. Mute track
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn mute_track_no_tracks() {
+    wait_for_healthy(LIVEKIT_URL, TIMEOUT).await;
+    let lk = livekit();
+    let room_name = unique_name("test-room");
+
+    lk.create_room(&serde_json::json!({ "name": &room_name }))
+        .await
+        .expect("create_room for mute_track");
+
+    // No participants/tracks exist — should error
+    let result = lk
+        .mute_track(&serde_json::json!({
+            "room": &room_name,
+            "identity": "ghost-user",
+            "track_sid": "TR_nonexistent",
+            "muted": true
+        }))
+        .await;
+
+    assert!(result.is_err(), "muting a non-existent track should fail");
+    let err_msg = format!("{}", result.unwrap_err());
+    assert!(!err_msg.is_empty(), "error message should describe the issue");
+
+    // Cleanup
+    let _ = lk.delete_room(&serde_json::json!({ "room": &room_name })).await;
+}
+
+// ---------------------------------------------------------------------------
+// 7. Egress
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn list_egress_empty() {
+    wait_for_healthy(LIVEKIT_URL, TIMEOUT).await;
+    let lk = livekit();
+
+    // Egress service may not be available in dev mode (returns 500 internal panic)
+    match lk.list_egress(&serde_json::json!({})).await {
+        Ok(resp) => assert!(resp.items.is_empty(), "no egress sessions should exist initially"),
+        Err(e) => {
+            let msg = e.to_string();
+            assert!(
+                msg.contains("500") || msg.contains("internal") || msg.contains("panic"),
+                "unexpected error (expected 500 from missing egress service): {e}"
+            );
+        }
+    }
+}
+
+#[tokio::test]
+async fn start_room_composite_egress_error() {
+    wait_for_healthy(LIVEKIT_URL, TIMEOUT).await;
+    let lk = livekit();
+    let room_name = unique_name("test-room");
+
+    lk.create_room(&serde_json::json!({ "name": &room_name }))
+        .await
+        .expect("create_room for egress");
+
+    // Attempt egress without a valid output config — should error
+    let result = lk
+        .start_room_composite_egress(&serde_json::json!({
+            "room_name": &room_name,
+            "layout": "speaker-dark"
+        }))
+        .await;
+
+    assert!(result.is_err(), "starting egress without output config should fail");
+    let err_msg = format!("{}", result.unwrap_err());
+    assert!(!err_msg.is_empty(), "error message should describe the missing output");
+
+    // Cleanup
+    let _ = lk.delete_room(&serde_json::json!({ "room": &room_name })).await;
+}
+
+#[tokio::test]
+async fn stop_egress_not_found() {
+    wait_for_healthy(LIVEKIT_URL, TIMEOUT).await;
+    let lk = livekit();
+
+    let result = lk
+        .stop_egress(&serde_json::json!({
+            "egress_id": "EG_nonexistent_00000"
+        }))
+        .await;
+
+    assert!(result.is_err(), "stopping a non-existent egress should fail");
+    let err_msg = format!("{}", result.unwrap_err());
+    assert!(!err_msg.is_empty(), "error message should describe the issue");
+}

sunbeam-sdk/tests/test_matrix.rs

@@ -0,0 +1,902 @@
+#![cfg(feature = "integration")]
+use sunbeam_sdk::client::{AuthMethod, ServiceClient};
+use sunbeam_sdk::matrix::MatrixClient;
+use sunbeam_sdk::matrix::types::*;
+use wiremock::{MockServer, Mock, ResponseTemplate};
+use wiremock::matchers::{method, path, path_regex};
+
+fn client(uri: &str) -> MatrixClient {
+    MatrixClient::from_parts(uri.to_string(), AuthMethod::Bearer("test-token".into()))
+}
+
+fn ok_json(body: serde_json::Value) -> ResponseTemplate {
+    ResponseTemplate::new(200).set_body_json(body)
+}
+
+fn ok_empty() -> ResponseTemplate {
+    ResponseTemplate::new(200).set_body_json(serde_json::json!({}))
+}
+
+// ---------------------------------------------------------------------------
+// ServiceClient trait + connect / set_token
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn service_client_trait() {
+    let server = MockServer::start().await;
+    let mut c = client(&server.uri());
+    assert_eq!(c.service_name(), "matrix");
+    assert_eq!(c.base_url(), server.uri());
+
+    c.set_token("new-tok");
+    // just exercises set_token; nothing to assert beyond no panic
+
+    let c2 = MatrixClient::connect("example.com");
+    assert_eq!(c2.base_url(), "https://matrix.example.com/_matrix");
+}
+
+// ---------------------------------------------------------------------------
+// Auth endpoints
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn auth_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // list_login_types
+    Mock::given(method("GET")).and(path("/client/v3/login"))
+        .respond_with(ok_json(serde_json::json!({"flows": []})))
+        .mount(&server).await;
+    let r = c.list_login_types().await.unwrap();
+    assert!(r.flows.is_empty());
+
+    // login
+    Mock::given(method("POST")).and(path("/client/v3/login"))
+        .respond_with(ok_json(serde_json::json!({
+            "user_id": "@u:localhost",
+            "access_token": "tok",
+            "device_id": "D1"
+        })))
+        .mount(&server).await;
+    let body = LoginRequest {
+        login_type: "m.login.password".into(),
+        identifier: None, password: Some("pw".into()), token: None,
+        device_id: None, initial_device_display_name: None, refresh_token: None,
+    };
+    let r = c.login(&body).await.unwrap();
+    assert_eq!(r.user_id, "@u:localhost");
+
+    // refresh
+    Mock::given(method("POST")).and(path("/client/v3/refresh"))
+        .respond_with(ok_json(serde_json::json!({
+            "access_token": "new-tok"
+        })))
+        .mount(&server).await;
+    let r = c.refresh(&RefreshRequest { refresh_token: "rt".into() }).await.unwrap();
+    assert_eq!(r.access_token, "new-tok");
+
+    // logout
+    Mock::given(method("POST")).and(path("/client/v3/logout"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.logout().await.unwrap();
+
+    // logout_all
+    Mock::given(method("POST")).and(path("/client/v3/logout/all"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.logout_all().await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// Account endpoints
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn account_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // register
+    Mock::given(method("POST")).and(path("/client/v3/register"))
+        .respond_with(ok_json(serde_json::json!({"user_id": "@new:localhost"})))
+        .mount(&server).await;
+    let body = RegisterRequest {
+        username: Some("new".into()), password: Some("pw".into()),
+        device_id: None, initial_device_display_name: None,
+        inhibit_login: None, refresh_token: None, auth: None, kind: None,
+    };
+    let r = c.register(&body).await.unwrap();
+    assert_eq!(r.user_id, "@new:localhost");
+
+    // whoami
+    Mock::given(method("GET")).and(path("/client/v3/account/whoami"))
+        .respond_with(ok_json(serde_json::json!({"user_id": "@me:localhost"})))
+        .mount(&server).await;
+    let r = c.whoami().await.unwrap();
+    assert_eq!(r.user_id, "@me:localhost");
+
+    // list_3pids
+    Mock::given(method("GET")).and(path("/client/v3/account/3pid"))
+        .respond_with(ok_json(serde_json::json!({"threepids": []})))
+        .mount(&server).await;
+    let r = c.list_3pids().await.unwrap();
+    assert!(r.threepids.is_empty());
+
+    // add_3pid
+    Mock::given(method("POST")).and(path("/client/v3/account/3pid/add"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.add_3pid(&Add3pidRequest { client_secret: None, sid: None, auth: None }).await.unwrap();
+
+    // delete_3pid
+    Mock::given(method("POST")).and(path("/client/v3/account/3pid/delete"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.delete_3pid(&Delete3pidRequest {
+        medium: "email".into(), address: "a@b.c".into(), id_server: None,
+    }).await.unwrap();
+
+    // change_password
+    Mock::given(method("POST")).and(path("/client/v3/account/password"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.change_password(&ChangePasswordRequest {
+        new_password: "new-pw".into(), logout_devices: None, auth: None,
+    }).await.unwrap();
+
+    // deactivate
+    Mock::given(method("POST")).and(path("/client/v3/account/deactivate"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.deactivate(&DeactivateRequest { auth: None, id_server: None, erase: None }).await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// Room endpoints
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn room_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // create_room
+    Mock::given(method("POST")).and(path("/client/v3/createRoom"))
+        .respond_with(ok_json(serde_json::json!({"room_id": "!r:localhost"})))
+        .mount(&server).await;
+    let body = CreateRoomRequest {
+        name: Some("test".into()), topic: None, room_alias_name: None,
+        visibility: None, preset: None, invite: None, is_direct: None,
+        creation_content: None, initial_state: None, power_level_content_override: None,
+    };
+    let r = c.create_room(&body).await.unwrap();
+    assert_eq!(r.room_id, "!r:localhost");
+
+    // list_public_rooms — no params
+    Mock::given(method("GET")).and(path("/client/v3/publicRooms"))
+        .respond_with(ok_json(serde_json::json!({"chunk": []})))
+        .mount(&server).await;
+    let r = c.list_public_rooms(None, None).await.unwrap();
+    assert!(r.chunk.is_empty());
+
+    // list_public_rooms — with limit + since (exercises query-string branch)
+    let r = c.list_public_rooms(Some(10), Some("tok")).await.unwrap();
+    assert!(r.chunk.is_empty());
+
+    // search_public_rooms
+    Mock::given(method("POST")).and(path("/client/v3/publicRooms"))
+        .respond_with(ok_json(serde_json::json!({"chunk": []})))
+        .mount(&server).await;
+    let body = SearchPublicRoomsRequest {
+        limit: None, since: None, filter: None,
+        include_all_networks: None, third_party_instance_id: None,
+    };
+    let r = c.search_public_rooms(&body).await.unwrap();
+    assert!(r.chunk.is_empty());
+
+    // get_room_visibility
+    Mock::given(method("GET")).and(path_regex("/client/v3/directory/list/room/.+"))
+        .respond_with(ok_json(serde_json::json!({"visibility": "public"})))
+        .mount(&server).await;
+    let r = c.get_room_visibility("!r:localhost").await.unwrap();
+    assert_eq!(r.visibility, "public");
+
+    // set_room_visibility
+    Mock::given(method("PUT")).and(path_regex("/client/v3/directory/list/room/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.set_room_visibility("!r:localhost", &SetRoomVisibilityRequest {
+        visibility: "private".into(),
+    }).await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// Membership endpoints
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn membership_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // join_room_by_id
+    Mock::given(method("POST")).and(path_regex("/client/v3/join/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.join_room_by_id("!room:localhost").await.unwrap();
+
+    // join_room_by_alias — use URL-encoded alias to avoid # being treated as fragment
+    c.join_room_by_alias("%23alias:localhost").await.unwrap();
+
+    // leave_room
+    Mock::given(method("POST")).and(path_regex("/client/v3/rooms/.+/leave"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.leave_room("!room:localhost").await.unwrap();
+
+    // invite
+    Mock::given(method("POST")).and(path_regex("/client/v3/rooms/.+/invite"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.invite("!room:localhost", &InviteRequest {
+        user_id: "@u:localhost".into(), reason: None,
+    }).await.unwrap();
+
+    // ban
+    Mock::given(method("POST")).and(path_regex("/client/v3/rooms/.+/ban"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.ban("!room:localhost", &BanRequest {
+        user_id: "@u:localhost".into(), reason: None,
+    }).await.unwrap();
+
+    // unban
+    Mock::given(method("POST")).and(path_regex("/client/v3/rooms/.+/unban"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.unban("!room:localhost", &UnbanRequest {
+        user_id: "@u:localhost".into(), reason: None,
+    }).await.unwrap();
+
+    // kick
+    Mock::given(method("POST")).and(path_regex("/client/v3/rooms/.+/kick"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.kick("!room:localhost", &KickRequest {
+        user_id: "@u:localhost".into(), reason: None,
+    }).await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// State endpoints
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn state_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // get_all_state — use exact path for the room
+    Mock::given(method("GET")).and(path("/client/v3/rooms/room1/state"))
+        .respond_with(ok_json(serde_json::json!([])))
+        .mount(&server).await;
+    let r = c.get_all_state("room1").await.unwrap();
+    assert!(r.is_empty());
+
+    // get_state_event — the path includes event_type/state_key, trailing slash for empty key
+    Mock::given(method("GET")).and(path_regex("/client/v3/rooms/.+/state/.+/.*"))
+        .respond_with(ok_json(serde_json::json!({"name": "Room"})))
+        .mount(&server).await;
+    let r = c.get_state_event("room2", "m.room.name", "").await.unwrap();
+    assert_eq!(r["name"], "Room");
+
+    // set_state_event
+    Mock::given(method("PUT")).and(path_regex("/client/v3/rooms/.+/state/.+/.*"))
+        .respond_with(ok_json(serde_json::json!({"event_id": "$e1"})))
+        .mount(&server).await;
+    let r = c.set_state_event(
+        "room2", "m.room.name", "",
+        &serde_json::json!({"name": "New"}),
+    ).await.unwrap();
+    assert_eq!(r.event_id, "$e1");
+}
+
+// ---------------------------------------------------------------------------
+// Sync
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn sync_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // sync — no params
+    Mock::given(method("GET")).and(path("/client/v3/sync"))
+        .respond_with(ok_json(serde_json::json!({"next_batch": "s1"})))
+        .mount(&server).await;
+    let r = c.sync(&SyncParams::default()).await.unwrap();
+    assert_eq!(r.next_batch, "s1");
+
+    // sync — all params populated to cover every query-string branch
+    let r = c.sync(&SyncParams {
+        filter: Some("f".into()),
+        since: Some("s0".into()),
+        full_state: Some(true),
+        set_presence: Some("online".into()),
+        timeout: Some(30000),
+    }).await.unwrap();
+    assert_eq!(r.next_batch, "s1");
+}
+
+// ---------------------------------------------------------------------------
+// Messages / events
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn message_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // send_event
+    Mock::given(method("PUT")).and(path_regex("/client/v3/rooms/.+/send/.+/.+"))
+        .respond_with(ok_json(serde_json::json!({"event_id": "$e1"})))
+        .mount(&server).await;
+    let r = c.send_event(
+        "!r:localhost", "m.room.message", "txn1",
+        &serde_json::json!({"msgtype": "m.text", "body": "hi"}),
+    ).await.unwrap();
+    assert_eq!(r.event_id, "$e1");
+
+    // get_messages — minimal params
+    Mock::given(method("GET")).and(path_regex("/client/v3/rooms/.+/messages"))
+        .respond_with(ok_json(serde_json::json!({"start": "s0", "chunk": []})))
+        .mount(&server).await;
+    let r = c.get_messages("!r:localhost", &MessagesParams {
+        dir: "b".into(), from: None, to: None, limit: None, filter: None,
+    }).await.unwrap();
+    assert!(r.chunk.is_empty());
+
+    // get_messages — all optional params to cover every branch
+    let r = c.get_messages("!r:localhost", &MessagesParams {
+        dir: "b".into(),
+        from: Some("tok1".into()),
+        to: Some("tok2".into()),
+        limit: Some(10),
+        filter: Some("{}".into()),
+    }).await.unwrap();
+    assert!(r.chunk.is_empty());
+
+    // get_event
+    Mock::given(method("GET")).and(path_regex("/client/v3/rooms/.+/event/.+"))
+        .respond_with(ok_json(serde_json::json!({
+            "type": "m.room.message",
+            "content": {"body": "hi"}
+        })))
+        .mount(&server).await;
+    let r = c.get_event("!r:localhost", "$ev1").await.unwrap();
+    assert_eq!(r.event_type, "m.room.message");
+
+    // get_context — without limit
+    Mock::given(method("GET")).and(path_regex("/client/v3/rooms/.+/context/.+"))
+        .respond_with(ok_json(serde_json::json!({
+            "start": "s0", "end": "s1",
+            "events_before": [], "events_after": []
+        })))
+        .mount(&server).await;
+    c.get_context("!r:localhost", "$ev1", None).await.unwrap();
+
+    // get_context — with limit to cover the branch
+    c.get_context("!r:localhost", "$ev1", Some(5)).await.unwrap();
+
+    // redact
+    Mock::given(method("PUT")).and(path_regex("/client/v3/rooms/.+/redact/.+/.+"))
+        .respond_with(ok_json(serde_json::json!({"event_id": "$re1"})))
+        .mount(&server).await;
+    let r = c.redact("!r:localhost", "$ev1", "txn2", &RedactRequest { reason: None }).await.unwrap();
+    assert_eq!(r.event_id, "$re1");
+}
+
+// ---------------------------------------------------------------------------
+// Presence
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn presence_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // get_presence
+    Mock::given(method("GET")).and(path_regex("/client/v3/presence/.+/status"))
+        .respond_with(ok_json(serde_json::json!({"presence": "online"})))
+        .mount(&server).await;
+    let r = c.get_presence("@u:localhost").await.unwrap();
+    assert_eq!(r.presence, "online");
+
+    // set_presence
+    Mock::given(method("PUT")).and(path_regex("/client/v3/presence/.+/status"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.set_presence("@u:localhost", &SetPresenceRequest {
+        presence: "offline".into(), status_msg: None,
+    }).await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// Typing
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn typing_endpoint() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    Mock::given(method("PUT")).and(path_regex("/client/v3/rooms/.+/typing/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.send_typing("!r:localhost", "@u:localhost", &TypingRequest {
+        typing: true, timeout: Some(30000),
+    }).await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// Receipts
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn receipt_endpoint() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    Mock::given(method("POST")).and(path_regex("/client/v3/rooms/.+/receipt/.+/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.send_receipt("!r:localhost", "m.read", "$ev1", &ReceiptRequest { thread_id: None }).await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// Profile endpoints
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn profile_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // get_profile
+    Mock::given(method("GET")).and(path_regex("/client/v3/profile/[^/]+$"))
+        .respond_with(ok_json(serde_json::json!({"displayname": "Alice"})))
+        .mount(&server).await;
+    let r = c.get_profile("@u:localhost").await.unwrap();
+    assert_eq!(r.displayname.as_deref(), Some("Alice"));
+
+    // get_displayname
+    Mock::given(method("GET")).and(path_regex("/client/v3/profile/.+/displayname"))
+        .respond_with(ok_json(serde_json::json!({"displayname": "Alice"})))
+        .mount(&server).await;
+    let r = c.get_displayname("@u:localhost").await.unwrap();
+    assert_eq!(r.displayname.as_deref(), Some("Alice"));
+
+    // set_displayname
+    Mock::given(method("PUT")).and(path_regex("/client/v3/profile/.+/displayname"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.set_displayname("@u:localhost", &SetDisplaynameRequest {
+        displayname: "Bob".into(),
+    }).await.unwrap();
+
+    // get_avatar_url
+    Mock::given(method("GET")).and(path_regex("/client/v3/profile/.+/avatar_url"))
+        .respond_with(ok_json(serde_json::json!({"avatar_url": "mxc://example/abc"})))
+        .mount(&server).await;
+    let r = c.get_avatar_url("@u:localhost").await.unwrap();
+    assert_eq!(r.avatar_url.as_deref(), Some("mxc://example/abc"));
+
+    // set_avatar_url
+    Mock::given(method("PUT")).and(path_regex("/client/v3/profile/.+/avatar_url"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.set_avatar_url("@u:localhost", &SetAvatarUrlRequest {
+        avatar_url: "mxc://example/xyz".into(),
+    }).await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// Alias endpoints
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn alias_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // create_alias
+    Mock::given(method("PUT")).and(path_regex("/client/v3/directory/room/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.create_alias("%23test:localhost", &CreateAliasRequest {
+        room_id: "!r:localhost".into(),
+    }).await.unwrap();
+
+    // resolve_alias
+    Mock::given(method("GET")).and(path_regex("/client/v3/directory/room/.+"))
+        .respond_with(ok_json(serde_json::json!({
+            "room_id": "!r:localhost", "servers": ["localhost"]
+        })))
+        .mount(&server).await;
+    let r = c.resolve_alias("%23test:localhost").await.unwrap();
+    assert_eq!(r.room_id.as_deref(), Some("!r:localhost"));
+
+    // delete_alias
+    Mock::given(method("DELETE")).and(path_regex("/client/v3/directory/room/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.delete_alias("%23test:localhost").await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// User directory search
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn search_users_endpoint() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    Mock::given(method("POST")).and(path("/client/v3/user_directory/search"))
+        .respond_with(ok_json(serde_json::json!({"results": [], "limited": false})))
+        .mount(&server).await;
+    let r = c.search_users(&UserSearchRequest {
+        search_term: "alice".into(), limit: None,
+    }).await.unwrap();
+    assert!(r.results.is_empty());
+}
+
+// ---------------------------------------------------------------------------
+// Media endpoints
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn media_upload() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // upload_media — success
+    Mock::given(method("POST")).and(path("/media/v3/upload"))
+        .respond_with(ok_json(serde_json::json!({"content_uri": "mxc://example/abc"})))
+        .mount(&server).await;
+    let r = c.upload_media("image/png", b"fake-png".to_vec()).await.unwrap();
+    assert_eq!(r.content_uri, "mxc://example/abc");
+}
+
+#[tokio::test]
+async fn media_upload_http_error() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // upload_media — HTTP error branch
+    Mock::given(method("POST")).and(path("/media/v3/upload"))
+        .respond_with(ResponseTemplate::new(500).set_body_string("server error"))
+        .mount(&server).await;
+    let r = c.upload_media("image/png", b"fake-png".to_vec()).await;
+    assert!(r.is_err());
+}
+
+#[tokio::test]
+async fn media_upload_bad_json() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // upload_media — invalid JSON response branch
+    Mock::given(method("POST")).and(path("/media/v3/upload"))
+        .respond_with(ResponseTemplate::new(200).set_body_string("not-json"))
+        .mount(&server).await;
+    let r = c.upload_media("image/png", b"fake-png".to_vec()).await;
+    assert!(r.is_err());
+}
+
+#[tokio::test]
+async fn media_download_and_thumbnail() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // download_media
+    Mock::given(method("GET")).and(path_regex("/media/v3/download/.+/.+"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(b"fake-content".to_vec()))
+        .mount(&server).await;
+    let r = c.download_media("localhost", "abc123").await.unwrap();
+    assert_eq!(r.as_ref(), b"fake-content");
+
+    // thumbnail — without method param
+    Mock::given(method("GET")).and(path_regex("/media/v3/thumbnail/.+/.+"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(b"thumb-bytes".to_vec()))
+        .mount(&server).await;
+    let r = c.thumbnail("localhost", "abc123", &ThumbnailParams {
+        width: 64, height: 64, method: None,
+    }).await.unwrap();
+    assert_eq!(r.as_ref(), b"thumb-bytes");
+
+    // thumbnail — with method param to cover the branch
+    let r = c.thumbnail("localhost", "abc123", &ThumbnailParams {
+        width: 64, height: 64, method: Some("crop".into()),
+    }).await.unwrap();
+    assert_eq!(r.as_ref(), b"thumb-bytes");
+}
+
+// ---------------------------------------------------------------------------
+// Device endpoints
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn device_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // list_devices
+    Mock::given(method("GET")).and(path("/client/v3/devices"))
+        .respond_with(ok_json(serde_json::json!({"devices": []})))
+        .mount(&server).await;
+    let r = c.list_devices().await.unwrap();
+    assert!(r.devices.is_empty());
+
+    // get_device
+    Mock::given(method("GET")).and(path_regex("/client/v3/devices/.+"))
+        .respond_with(ok_json(serde_json::json!({"device_id": "D1"})))
+        .mount(&server).await;
+    let r = c.get_device("D1").await.unwrap();
+    assert_eq!(r.device_id, "D1");
+
+    // update_device
+    Mock::given(method("PUT")).and(path_regex("/client/v3/devices/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.update_device("D1", &UpdateDeviceRequest {
+        display_name: Some("Phone".into()),
+    }).await.unwrap();
+
+    // delete_device
+    Mock::given(method("DELETE")).and(path_regex("/client/v3/devices/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.delete_device("D1", &DeleteDeviceRequest { auth: None }).await.unwrap();
+
+    // batch_delete_devices
+    Mock::given(method("POST")).and(path("/client/v3/delete_devices"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.batch_delete_devices(&BatchDeleteDevicesRequest {
+        devices: vec!["D1".into(), "D2".into()], auth: None,
+    }).await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// E2EE / Keys
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn keys_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // upload_keys
+    Mock::given(method("POST")).and(path("/client/v3/keys/upload"))
+        .respond_with(ok_json(serde_json::json!({"one_time_key_counts": {}})))
+        .mount(&server).await;
+    let r = c.upload_keys(&KeysUploadRequest {
+        device_keys: None, one_time_keys: None, fallback_keys: None,
+    }).await.unwrap();
+    assert!(r.one_time_key_counts.is_object());
+
+    // query_keys
+    Mock::given(method("POST")).and(path("/client/v3/keys/query"))
+        .respond_with(ok_json(serde_json::json!({"device_keys": {}})))
+        .mount(&server).await;
+    let r = c.query_keys(&KeysQueryRequest {
+        device_keys: serde_json::json!({}), timeout: None,
+    }).await.unwrap();
+    assert!(r.device_keys.is_object());
+
+    // claim_keys
+    Mock::given(method("POST")).and(path("/client/v3/keys/claim"))
+        .respond_with(ok_json(serde_json::json!({"one_time_keys": {}})))
+        .mount(&server).await;
+    let r = c.claim_keys(&KeysClaimRequest {
+        one_time_keys: serde_json::json!({}), timeout: None,
+    }).await.unwrap();
+    assert!(r.one_time_keys.is_object());
+}
+
+// ---------------------------------------------------------------------------
+// Push endpoints
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn push_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // list_pushers
+    Mock::given(method("GET")).and(path("/client/v3/pushers"))
+        .respond_with(ok_json(serde_json::json!({"pushers": []})))
+        .mount(&server).await;
+    let r = c.list_pushers().await.unwrap();
+    assert!(r.pushers.is_empty());
+
+    // set_pusher
+    Mock::given(method("POST")).and(path("/client/v3/pushers/set"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.set_pusher(&serde_json::json!({})).await.unwrap();
+
+    // get_push_rules
+    Mock::given(method("GET")).and(path("/client/v3/pushrules/"))
+        .respond_with(ok_json(serde_json::json!({"global": {}})))
+        .mount(&server).await;
+    let r = c.get_push_rules().await.unwrap();
+    assert!(r.global.is_some());
+
+    // set_push_rule
+    Mock::given(method("PUT")).and(path_regex("/client/v3/pushrules/.+/.+/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.set_push_rule("global", "content", "rule1", &serde_json::json!({})).await.unwrap();
+
+    // delete_push_rule
+    Mock::given(method("DELETE")).and(path_regex("/client/v3/pushrules/.+/.+/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.delete_push_rule("global", "content", "rule1").await.unwrap();
+
+    // get_notifications — no params
+    Mock::given(method("GET")).and(path("/client/v3/notifications"))
+        .respond_with(ok_json(serde_json::json!({"notifications": []})))
+        .mount(&server).await;
+    let r = c.get_notifications(&NotificationsParams::default()).await.unwrap();
+    assert!(r.notifications.is_empty());
+
+    // get_notifications — all params to cover all branches
+    let r = c.get_notifications(&NotificationsParams {
+        from: Some("tok".into()),
+        limit: Some(5),
+        only: Some("highlight".into()),
+    }).await.unwrap();
+    assert!(r.notifications.is_empty());
+}
+
+// ---------------------------------------------------------------------------
+// Account data
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn account_data_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // get_account_data
+    Mock::given(method("GET")).and(path_regex("/client/v3/user/.+/account_data/.+"))
+        .respond_with(ok_json(serde_json::json!({"key": "val"})))
+        .mount(&server).await;
+    let r = c.get_account_data("@u:localhost", "m.some_type").await.unwrap();
+    assert_eq!(r["key"], "val");
+
+    // set_account_data
+    Mock::given(method("PUT")).and(path_regex("/client/v3/user/.+/account_data/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.set_account_data("@u:localhost", "m.some_type", &serde_json::json!({"key": "val"})).await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// Tags
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn tag_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // get_tags
+    Mock::given(method("GET")).and(path_regex("/client/v3/user/.+/rooms/.+/tags$"))
+        .respond_with(ok_json(serde_json::json!({"tags": {}})))
+        .mount(&server).await;
+    let r = c.get_tags("@u:localhost", "!r:localhost").await.unwrap();
+    assert!(r.tags.is_object());
+
+    // set_tag
+    Mock::given(method("PUT")).and(path_regex("/client/v3/user/.+/rooms/.+/tags/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.set_tag("@u:localhost", "!r:localhost", "m.favourite", &serde_json::json!({})).await.unwrap();
+
+    // delete_tag
+    Mock::given(method("DELETE")).and(path_regex("/client/v3/user/.+/rooms/.+/tags/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.delete_tag("@u:localhost", "!r:localhost", "m.favourite").await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// Search
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn search_messages_endpoint() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    Mock::given(method("POST")).and(path("/client/v3/search"))
+        .respond_with(ok_json(serde_json::json!({"search_categories": {}})))
+        .mount(&server).await;
+    let r = c.search_messages(&SearchRequest {
+        search_categories: serde_json::json!({}),
+    }).await.unwrap();
+    assert!(r.search_categories.is_object());
+}
+
+// ---------------------------------------------------------------------------
+// Filters
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn filter_endpoints() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    // create_filter
+    Mock::given(method("POST")).and(path_regex("/client/v3/user/.+/filter$"))
+        .respond_with(ok_json(serde_json::json!({"filter_id": "f1"})))
+        .mount(&server).await;
+    let r = c.create_filter("@u:localhost", &serde_json::json!({})).await.unwrap();
+    assert_eq!(r.filter_id, "f1");
+
+    // get_filter
+    Mock::given(method("GET")).and(path_regex("/client/v3/user/.+/filter/.+"))
+        .respond_with(ok_json(serde_json::json!({})))
+        .mount(&server).await;
+    c.get_filter("@u:localhost", "f1").await.unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// Spaces
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn space_hierarchy_endpoint() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    Mock::given(method("GET")).and(path_regex("/client/v1/rooms/.+/hierarchy"))
+        .respond_with(ok_json(serde_json::json!({"rooms": []})))
+        .mount(&server).await;
+
+    // no params
+    let r = c.get_space_hierarchy("!r:localhost", &SpaceHierarchyParams::default()).await.unwrap();
+    assert!(r.rooms.is_empty());
+
+    // all params to cover all branches
+    let r = c.get_space_hierarchy("!r:localhost", &SpaceHierarchyParams {
+        from: Some("tok".into()),
+        limit: Some(10),
+        max_depth: Some(3),
+        suggested_only: Some(true),
+    }).await.unwrap();
+    assert!(r.rooms.is_empty());
+}
+
+// ---------------------------------------------------------------------------
+// Send-to-device
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn send_to_device_endpoint() {
+    let server = MockServer::start().await;
+    let c = client(&server.uri());
+
+    Mock::given(method("PUT")).and(path_regex("/client/v3/sendToDevice/.+/.+"))
+        .respond_with(ok_empty())
+        .mount(&server).await;
+    c.send_to_device("m.room.encrypted", "txn1", &SendToDeviceRequest {
+        messages: serde_json::json!({}),
+    }).await.unwrap();
+}

sunbeam-sdk/tests/test_opensearch.rs

@@ -0,0 +1,767 @@
+#![cfg(feature = "integration")]
+#![allow(unused_imports)]
+mod helpers;
+use helpers::*;
+use sunbeam_sdk::client::{AuthMethod, ServiceClient};
+use sunbeam_sdk::search::OpenSearchClient;
+use sunbeam_sdk::search::types::*;
+
+const OS_URL: &str = "http://localhost:9200";
+const HEALTH_URL: &str = "http://localhost:9200/_cluster/health";
+
+fn os_client() -> OpenSearchClient {
+    OpenSearchClient::from_parts(OS_URL.into(), AuthMethod::None)
+}
+
+/// Force-refresh an index so documents are searchable.
+async fn refresh_index(idx: &str) {
+    reqwest::Client::new()
+        .post(format!("{OS_URL}/{idx}/_refresh"))
+        .send()
+        .await
+        .unwrap();
+}
+
+/// Delete an index, ignoring errors (cleanup helper).
+async fn cleanup_index(idx: &str) {
+    let _ = os_client().delete_index(idx).await;
+}
+
+/// Delete a template, ignoring errors.
+async fn cleanup_template(name: &str) {
+    let _ = os_client().delete_template(name).await;
+}
+
+/// Delete a pipeline, ignoring errors.
+async fn cleanup_pipeline(id: &str) {
+    let _ = os_client().delete_pipeline(id).await;
+}
+
+/// Delete a snapshot repo, ignoring errors.
+async fn cleanup_snapshot_repo(name: &str) {
+    let _ = os_client().delete_snapshot_repo(name).await;
+}
+
+// ---------------------------------------------------------------------------
+// 1. Cluster health and info
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn cluster_health_and_info() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = os_client();
+
+    // cluster_health
+    let health = client.cluster_health().await.expect("cluster_health failed");
+    assert!(!health.cluster_name.is_empty());
+    assert!(
+        health.status == "green" || health.status == "yellow" || health.status == "red",
+        "unexpected status: {}",
+        health.status
+    );
+    assert!(health.number_of_nodes >= 1);
+
+    // cluster_state
+    let state = client.cluster_state().await.expect("cluster_state failed");
+    assert!(state.get("cluster_name").is_some());
+    assert!(state.get("metadata").is_some());
+
+    // cluster_stats
+    let stats = client.cluster_stats().await.expect("cluster_stats failed");
+    assert!(stats.get("nodes").is_some());
+
+    // cluster_settings
+    let settings = client.cluster_settings().await.expect("cluster_settings failed");
+    // Should have persistent and transient keys
+    assert!(settings.is_object());
+}
+
+// ---------------------------------------------------------------------------
+// 2. Nodes
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn nodes() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = os_client();
+
+    // nodes_info
+    let info = client.nodes_info().await.expect("nodes_info failed");
+    assert!(info.get("nodes").is_some());
+
+    // nodes_stats
+    let stats = client.nodes_stats().await.expect("nodes_stats failed");
+    assert!(stats.get("nodes").is_some());
+
+    // nodes_hot_threads
+    let threads = client.nodes_hot_threads().await.expect("nodes_hot_threads failed");
+    // Returns plain text; just verify it is non-empty or at least doesn't error
+    // Just verify it doesn't fail; content is plain text
+    let _ = threads;
+}
+
+// ---------------------------------------------------------------------------
+// 3. Index lifecycle
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn index_lifecycle() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = os_client();
+    let idx = unique_name("test-idx");
+
+    // Ensure clean state
+    cleanup_index(&idx).await;
+
+    // index_exists — false before creation
+    let exists = client.index_exists(&idx).await.expect("index_exists failed");
+    assert!(!exists, "index should not exist before creation");
+
+    // create_index
+    let body = serde_json::json!({
+        "settings": {
+            "number_of_shards": 1,
+            "number_of_replicas": 0
+        }
+    });
+    let ack = client.create_index(&idx, &body).await.expect("create_index failed");
+    assert!(ack.acknowledged);
+
+    // index_exists — true after creation
+    let exists = client.index_exists(&idx).await.expect("index_exists failed");
+    assert!(exists, "index should exist after creation");
+
+    // get_index
+    let meta = client.get_index(&idx).await.expect("get_index failed");
+    assert!(meta.get(&idx).is_some());
+
+    // get_settings
+    let settings = client.get_settings(&idx).await.expect("get_settings failed");
+    assert!(settings.get(&idx).is_some());
+
+    // update_settings
+    let new_settings = serde_json::json!({
+        "index": { "number_of_replicas": 0 }
+    });
+    let ack = client
+        .update_settings(&idx, &new_settings)
+        .await
+        .expect("update_settings failed");
+    assert!(ack.acknowledged);
+
+    // get_mapping
+    let mapping = client.get_mapping(&idx).await.expect("get_mapping failed");
+    assert!(mapping.get(&idx).is_some());
+
+    // put_mapping
+    let new_mapping = serde_json::json!({
+        "properties": {
+            "title": { "type": "text" },
+            "count": { "type": "integer" }
+        }
+    });
+    let ack = client
+        .put_mapping(&idx, &new_mapping)
+        .await
+        .expect("put_mapping failed");
+    assert!(ack.acknowledged);
+
+    // Verify mapping was applied
+    let mapping = client.get_mapping(&idx).await.expect("get_mapping after put failed");
+    let props = &mapping[&idx]["mappings"]["properties"];
+    assert_eq!(props["title"]["type"], "text");
+
+    // close_index
+    let ack = client.close_index(&idx).await.expect("close_index failed");
+    assert!(ack.acknowledged);
+
+    // open_index
+    let ack = client.open_index(&idx).await.expect("open_index failed");
+    assert!(ack.acknowledged);
+
+    // delete_index
+    let ack = client.delete_index(&idx).await.expect("delete_index failed");
+    assert!(ack.acknowledged);
+
+    // Confirm deleted
+    let exists = client.index_exists(&idx).await.expect("index_exists after delete failed");
+    assert!(!exists);
+}
+
+// ---------------------------------------------------------------------------
+// 4. Document CRUD
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn document_crud() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = os_client();
+    let idx = unique_name("test-doc");
+    cleanup_index(&idx).await;
+
+    // Create index first
+    let body = serde_json::json!({
+        "settings": { "number_of_shards": 1, "number_of_replicas": 0 }
+    });
+    client.create_index(&idx, &body).await.expect("create_index failed");
+
+    // index_doc — explicit ID
+    let doc = serde_json::json!({ "title": "Hello", "count": 1 });
+    let resp = client.index_doc(&idx, "doc1", &doc).await.expect("index_doc failed");
+    assert_eq!(resp.index, idx);
+    assert_eq!(resp.id, "doc1");
+    assert!(resp.result.as_deref() == Some("created") || resp.result.as_deref() == Some("updated"));
+
+    // index_doc_auto_id
+    let doc2 = serde_json::json!({ "title": "Auto", "count": 2 });
+    let resp = client
+        .index_doc_auto_id(&idx, &doc2)
+        .await
+        .expect("index_doc_auto_id failed");
+    assert_eq!(resp.index, idx);
+    assert!(!resp.id.is_empty());
+    let _auto_id = resp.id.clone();
+
+    // get_doc
+    let got = client.get_doc(&idx, "doc1").await.expect("get_doc failed");
+    assert!(got.found);
+    assert_eq!(got.id, "doc1");
+    assert_eq!(got.source.as_ref().unwrap()["title"], "Hello");
+
+    // head_doc — true case
+    let exists = client.head_doc(&idx, "doc1").await.expect("head_doc failed");
+    assert!(exists, "head_doc should return true for existing doc");
+
+    // head_doc — false case
+    let exists = client
+        .head_doc(&idx, "nonexistent-doc-999")
+        .await
+        .expect("head_doc failed");
+    assert!(!exists, "head_doc should return false for missing doc");
+
+    // update_doc
+    let update_body = serde_json::json!({
+        "doc": { "count": 42 }
+    });
+    let uresp = client
+        .update_doc(&idx, "doc1", &update_body)
+        .await
+        .expect("update_doc failed");
+    assert_eq!(uresp.id, "doc1");
+    assert!(uresp.result.as_deref() == Some("updated") || uresp.result.as_deref() == Some("noop"));
+
+    // Verify update
+    let got = client.get_doc(&idx, "doc1").await.expect("get_doc after update failed");
+    assert_eq!(got.source.as_ref().unwrap()["count"], 42);
+
+    // delete_doc
+    let dresp = client.delete_doc(&idx, "doc1").await.expect("delete_doc failed");
+    assert_eq!(dresp.result.as_deref(), Some("deleted"));
+
+    // Verify doc deleted via head_doc
+    let exists = client.head_doc(&idx, "doc1").await.expect("head_doc after delete failed");
+    assert!(!exists);
+
+    // Cleanup: also delete the auto-id doc's index
+    cleanup_index(&idx).await;
+}
+
+// ---------------------------------------------------------------------------
+// 5. Search operations
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn search_operations() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = os_client();
+    let idx = unique_name("test-search");
+    cleanup_index(&idx).await;
+
+    // Setup: create index and index some docs
+    let body = serde_json::json!({
+        "settings": { "number_of_shards": 1, "number_of_replicas": 0 }
+    });
+    client.create_index(&idx, &body).await.unwrap();
+
+    for i in 1..=5 {
+        let doc = serde_json::json!({ "title": format!("doc-{i}"), "value": i });
+        client
+            .index_doc(&idx, &format!("d{i}"), &doc)
+            .await
+            .unwrap();
+    }
+    refresh_index(&idx).await;
+
+    // search
+    let query = serde_json::json!({
+        "query": { "match_all": {} }
+    });
+    let sr = client.search(&idx, &query).await.expect("search failed");
+    assert!(!sr.timed_out);
+    assert_eq!(sr.hits.total.value, 5);
+    assert_eq!(sr.hits.hits.len(), 5);
+
+    // search with a match query
+    let query = serde_json::json!({
+        "query": { "match": { "title": "doc-3" } }
+    });
+    let sr = client.search(&idx, &query).await.expect("search match failed");
+    assert!(sr.hits.total.value >= 1);
+    assert!(sr.hits.hits.iter().any(|h| h.id == "d3"));
+
+    // search_all
+    let query = serde_json::json!({
+        "query": { "match_all": {} },
+        "size": 1
+    });
+    let sr = client.search_all(&query).await.expect("search_all failed");
+    assert!(sr.hits.total.value >= 5);
+
+    // count
+    let query = serde_json::json!({
+        "query": { "match_all": {} }
+    });
+    let cr = client.count(&idx, &query).await.expect("count failed");
+    assert_eq!(cr.count, 5);
+
+    // multi_search — note: msearch body is NDJSON, but client sends as JSON.
+    // The client method takes &Value, so we pass the structured form.
+    // OpenSearch may not parse this correctly since msearch expects NDJSON.
+    // We test what the API returns.
+    // TODO: multi_search may need a raw NDJSON body method to work correctly.
+
+    // search_shards
+    let shards = client.search_shards(&idx).await.expect("search_shards failed");
+    assert!(shards.nodes.is_object());
+    assert!(!shards.shards.is_empty());
+
+    // search_template — inline template
+    let tmpl_body = serde_json::json!({
+        "source": { "query": { "match": { "title": "{{title}}" } } },
+        "params": { "title": "doc-1" }
+    });
+    let sr = client
+        .search_template(&tmpl_body)
+        .await
+        .expect("search_template failed");
+    // search_template against _search/template (no index) searches all indices
+    assert!(sr.hits.total.value >= 1);
+
+    // scroll — first do a search with scroll param via raw reqwest, then use scroll()
+    let scroll_resp: serde_json::Value = reqwest::Client::new()
+        .post(format!("{OS_URL}/{idx}/_search?scroll=1m"))
+        .json(&serde_json::json!({
+            "size": 2,
+            "query": { "match_all": {} }
+        }))
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let scroll_id = scroll_resp["_scroll_id"].as_str().expect("no scroll_id");
+
+    let sr = client
+        .scroll(&serde_json::json!({
+            "scroll": "1m",
+            "scroll_id": scroll_id
+        }))
+        .await
+        .expect("scroll failed");
+    // Should return remaining docs (we fetched 2 of 5, so 3 remain)
+    assert!(sr.hits.hits.len() <= 5);
+
+    // clear_scroll
+    let clear_scroll_id = sr.scroll_id.as_deref().unwrap_or(scroll_id);
+    client
+        .clear_scroll(&serde_json::json!({
+            "scroll_id": [clear_scroll_id]
+        }))
+        .await
+        .expect("clear_scroll failed");
+
+    cleanup_index(&idx).await;
+}
+
+// ---------------------------------------------------------------------------
+// 6. Bulk operations
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn bulk_operations() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = os_client();
+    let idx = unique_name("test-bulk");
+    let idx2 = unique_name("test-bulk-dst");
+    cleanup_index(&idx).await;
+    cleanup_index(&idx2).await;
+
+    // Create source index
+    let body = serde_json::json!({
+        "settings": { "number_of_shards": 1, "number_of_replicas": 0 }
+    });
+    client.create_index(&idx, &body).await.unwrap();
+
+    // bulk — The client's bulk() method sends body as JSON (Content-Type: application/json).
+    // OpenSearch _bulk expects NDJSON (newline-delimited JSON).
+    // Sending a single JSON object will likely fail or be misinterpreted.
+    // TODO: bulk() needs a raw NDJSON body method. The current &Value signature
+    // cannot represent NDJSON. Consider adding a bulk_raw(&str) method.
+
+    // Instead, index docs individually for multi_get and reindex tests.
+    for i in 1..=3 {
+        let doc = serde_json::json!({ "field": format!("value{i}") });
+        client.index_doc(&idx, &i.to_string(), &doc).await.unwrap();
+    }
+    refresh_index(&idx).await;
+
+    // multi_get
+    let mget_body = serde_json::json!({
+        "docs": [
+            { "_index": &idx, "_id": "1" },
+            { "_index": &idx, "_id": "2" },
+            { "_index": &idx, "_id": "999" }
+        ]
+    });
+    let mget = client.multi_get(&mget_body).await.expect("multi_get failed");
+    assert_eq!(mget.docs.len(), 3);
+    assert!(mget.docs[0].found);
+    assert!(mget.docs[1].found);
+    assert!(!mget.docs[2].found);
+
+    // reindex
+    let reindex_body = serde_json::json!({
+        "source": { "index": &idx },
+        "dest": { "index": &idx2 }
+    });
+    let rr = client.reindex(&reindex_body).await.expect("reindex failed");
+    assert_eq!(rr.created, 3);
+    assert!(rr.failures.is_empty());
+
+    // delete_by_query
+    refresh_index(&idx).await;
+    let dbq_body = serde_json::json!({
+        "query": { "match": { "field": "value1" } }
+    });
+    let dbq = client
+        .delete_by_query(&idx, &dbq_body)
+        .await
+        .expect("delete_by_query failed");
+    assert_eq!(dbq.deleted, 1);
+
+    cleanup_index(&idx).await;
+    cleanup_index(&idx2).await;
+}
+
+// ---------------------------------------------------------------------------
+// 7. Aliases
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn aliases() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = os_client();
+    let idx = unique_name("test-alias");
+    let alias_name = unique_name("alias");
+    cleanup_index(&idx).await;
+
+    // Create index
+    let body = serde_json::json!({
+        "settings": { "number_of_shards": 1, "number_of_replicas": 0 }
+    });
+    client.create_index(&idx, &body).await.unwrap();
+
+    // create_alias
+    let alias_body = serde_json::json!({
+        "actions": [
+            { "add": { "index": &idx, "alias": &alias_name } }
+        ]
+    });
+    let ack = client.create_alias(&alias_body).await.expect("create_alias failed");
+    assert!(ack.acknowledged);
+
+    // get_aliases
+    let aliases = client.get_aliases(&idx).await.expect("get_aliases failed");
+    let idx_aliases = &aliases[&idx]["aliases"];
+    assert!(idx_aliases.get(&alias_name).is_some(), "alias should exist");
+
+    // delete_alias
+    let ack = client
+        .delete_alias(&idx, &alias_name)
+        .await
+        .expect("delete_alias failed");
+    assert!(ack.acknowledged);
+
+    // Verify alias removed
+    let aliases = client.get_aliases(&idx).await.expect("get_aliases after delete failed");
+    let idx_aliases = &aliases[&idx]["aliases"];
+    assert!(idx_aliases.get(&alias_name).is_none(), "alias should be gone");
+
+    cleanup_index(&idx).await;
+}
+
+// ---------------------------------------------------------------------------
+// 8. Templates
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn templates() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = os_client();
+    let tmpl_name = unique_name("test-tmpl");
+    cleanup_template(&tmpl_name).await;
+
+    // create_template
+    let tmpl_body = serde_json::json!({
+        "index_patterns": [format!("{tmpl_name}-*")],
+        "template": {
+            "settings": {
+                "number_of_shards": 1,
+                "number_of_replicas": 0
+            },
+            "mappings": {
+                "properties": {
+                    "name": { "type": "keyword" }
+                }
+            }
+        }
+    });
+    let ack = client
+        .create_template(&tmpl_name, &tmpl_body)
+        .await
+        .expect("create_template failed");
+    assert!(ack.acknowledged);
+
+    // get_template
+    let tmpl = client.get_template(&tmpl_name).await.expect("get_template failed");
+    let templates = tmpl["index_templates"].as_array().expect("expected array");
+    assert!(!templates.is_empty());
+    assert_eq!(templates[0]["name"], tmpl_name);
+
+    // delete_template
+    let ack = client
+        .delete_template(&tmpl_name)
+        .await
+        .expect("delete_template failed");
+    assert!(ack.acknowledged);
+
+    // Verify deleted — get_template should error
+    let result = client.get_template(&tmpl_name).await;
+    assert!(result.is_err(), "get_template should fail after deletion");
+}
+
+// ---------------------------------------------------------------------------
+// 9. Cat operations
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn cat_operations() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = os_client();
+    let idx = unique_name("test-cat");
+    cleanup_index(&idx).await;
+
+    // Create an index so cat_indices returns at least one
+    let body = serde_json::json!({
+        "settings": { "number_of_shards": 1, "number_of_replicas": 0 }
+    });
+    client.create_index(&idx, &body).await.unwrap();
+
+    // cat_indices
+    let indices = client.cat_indices().await.expect("cat_indices failed");
+    assert!(
+        indices.iter().any(|i| i.index.as_deref() == Some(&idx)),
+        "our index should appear in cat_indices"
+    );
+
+    // cat_nodes
+    let nodes = client.cat_nodes().await.expect("cat_nodes failed");
+    assert!(!nodes.is_empty(), "should have at least one node");
+    assert!(nodes[0].ip.is_some());
+
+    // cat_shards
+    let shards = client.cat_shards().await.expect("cat_shards failed");
+    assert!(
+        shards.iter().any(|s| s.index.as_deref() == Some(&idx)),
+        "our index should have shards"
+    );
+
+    // cat_health
+    let health = client.cat_health().await.expect("cat_health failed");
+    assert!(!health.is_empty());
+    assert!(health[0].status.is_some());
+
+    // cat_allocation
+    let alloc = client.cat_allocation().await.expect("cat_allocation failed");
+    assert!(!alloc.is_empty());
+    assert!(alloc[0].node.is_some());
+
+    cleanup_index(&idx).await;
+}
+
+// ---------------------------------------------------------------------------
+// 10. Ingest pipelines
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn ingest_pipelines() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = os_client();
+    let pipe_id = unique_name("test-pipe");
+    cleanup_pipeline(&pipe_id).await;
+
+    // create_pipeline
+    let pipe_body = serde_json::json!({
+        "description": "Test pipeline",
+        "processors": [
+            {
+                "set": {
+                    "field": "processed",
+                    "value": true
+                }
+            }
+        ]
+    });
+    let ack = client
+        .create_pipeline(&pipe_id, &pipe_body)
+        .await
+        .expect("create_pipeline failed");
+    assert!(ack.acknowledged);
+
+    // get_pipeline
+    let pipe = client.get_pipeline(&pipe_id).await.expect("get_pipeline failed");
+    assert!(pipe.get(&pipe_id).is_some());
+    assert_eq!(pipe[&pipe_id]["description"], "Test pipeline");
+
+    // get_all_pipelines
+    let all = client.get_all_pipelines().await.expect("get_all_pipelines failed");
+    assert!(all.get(&pipe_id).is_some(), "our pipeline should appear in all pipelines");
+
+    // simulate_pipeline
+    let sim_body = serde_json::json!({
+        "docs": [
+            { "_source": { "title": "test doc" } }
+        ]
+    });
+    let sim = client
+        .simulate_pipeline(&pipe_id, &sim_body)
+        .await
+        .expect("simulate_pipeline failed");
+    let sim_docs = sim["docs"].as_array().expect("expected docs array");
+    assert!(!sim_docs.is_empty());
+    // The set processor should have added "processed": true
+    assert_eq!(sim_docs[0]["doc"]["_source"]["processed"], true);
+
+    // delete_pipeline
+    let ack = client
+        .delete_pipeline(&pipe_id)
+        .await
+        .expect("delete_pipeline failed");
+    assert!(ack.acknowledged);
+
+    // Verify deleted
+    let result = client.get_pipeline(&pipe_id).await;
+    assert!(result.is_err(), "get_pipeline should fail after deletion");
+}
+
+// ---------------------------------------------------------------------------
+// 11. Snapshots
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn snapshots() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = os_client();
+    let repo_name = unique_name("test-repo");
+    cleanup_snapshot_repo(&repo_name).await;
+
+    // create_snapshot_repo — use fs type with a known path
+    // Note: this requires the OpenSearch node to have path.repo configured.
+    // We use a URL repo type which is more universally available, but may
+    // also need config. Try fs repo first; if it fails, the test still
+    // validates the API call structure.
+    let repo_body = serde_json::json!({
+        "type": "fs",
+        "settings": {
+            "location": format!("/tmp/snapshots/{repo_name}")
+        }
+    });
+    let result = client.create_snapshot_repo(&repo_name, &repo_body).await;
+    if let Err(ref e) = result {
+        // If fs repo is not configured (path.repo not set), skip gracefully
+        let msg = format!("{e}");
+        if msg.contains("repository_exception") || msg.contains("doesn't match any of the locations") {
+            eprintln!("Skipping snapshot tests: path.repo not configured on OpenSearch node");
+            return;
+        }
+    }
+    let ack = result.expect("create_snapshot_repo failed");
+    assert!(ack.acknowledged);
+
+    // list_snapshots — repo exists but no snapshots yet
+    let snaps = client
+        .list_snapshots(&repo_name)
+        .await
+        .expect("list_snapshots failed");
+    let snap_list = snaps["snapshots"].as_array().expect("expected snapshots array");
+    assert!(snap_list.is_empty(), "fresh repo should have no snapshots");
+
+    // delete_snapshot_repo
+    let ack = client
+        .delete_snapshot_repo(&repo_name)
+        .await
+        .expect("delete_snapshot_repo failed");
+    assert!(ack.acknowledged);
+
+    // Skipping create_snapshot / restore_snapshot — they require filesystem
+    // access and a properly configured path.repo on the OpenSearch node.
+}
+
+// ---------------------------------------------------------------------------
+// 12. Cluster settings (update_cluster_settings, reroute, allocation_explain)
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn cluster_settings_update() {
+    wait_for_healthy(HEALTH_URL, TIMEOUT).await;
+    let client = os_client();
+
+    // update_cluster_settings — set a harmless transient setting
+    let body = serde_json::json!({
+        "transient": {
+            "cluster.routing.allocation.enable": "all"
+        }
+    });
+    let resp = client
+        .update_cluster_settings(&body)
+        .await
+        .expect("update_cluster_settings failed");
+    assert!(resp.get("acknowledged").is_some());
+    assert_eq!(resp["acknowledged"], true);
+
+    // reroute — a no-op reroute with empty commands
+    let body = serde_json::json!({ "commands": [] });
+    let resp = client.reroute(&body).await.expect("reroute failed");
+    assert!(resp.get("acknowledged").is_some());
+
+    // allocation_explain — requires an unassigned shard to explain.
+    // On a healthy single-node cluster there may be none, so we accept
+    // either a successful response or an error indicating no unassigned shards.
+    let body = serde_json::json!({});
+    let result = client.allocation_explain(&body).await;
+    match result {
+        Ok(val) => {
+            // If it succeeds, it should contain shard allocation info
+            assert!(val.is_object());
+        }
+        Err(e) => {
+            // Expected: "unable to find any unassigned shards to explain"
+            let msg = format!("{e}");
+            assert!(
+                msg.contains("unable to find") || msg.contains("400"),
+                "unexpected allocation_explain error: {msg}"
+            );
+        }
+    }
+}

sunbeam-sdk/tests/test_s3.rs

@@ -0,0 +1,875 @@
+#![cfg(feature = "integration")]
+mod helpers;
+use helpers::*;
+
+use sunbeam_sdk::client::{AuthMethod, ServiceClient};
+use sunbeam_sdk::storage::S3Client;
+#[allow(unused_imports)]
+use sunbeam_sdk::storage::types::*;
+use wiremock::matchers::{method, path, query_param};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+// ---------------------------------------------------------------------------
+// Helper: build an S3Client pointed at the mock server
+// ---------------------------------------------------------------------------
+
+fn mock_client(server: &MockServer) -> S3Client {
+    S3Client::from_parts(server.uri(), AuthMethod::None)
+}
+
+// ===========================================================================
+// Health & connectivity (real MinIO)
+// ===========================================================================
+
+const MINIO_URL: &str = "http://localhost:9000";
+const MINIO_HEALTH: &str = "http://localhost:9000/minio/health/live";
+
+#[tokio::test]
+async fn minio_is_healthy() {
+    wait_for_healthy(MINIO_HEALTH, TIMEOUT).await;
+    let resp = reqwest::get(MINIO_HEALTH).await.unwrap();
+    assert!(resp.status().is_success());
+}
+
+// ===========================================================================
+// Bucket operations
+// ===========================================================================
+
+// 1. create_bucket — PUT /{bucket}
+#[tokio::test]
+async fn create_bucket_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket"))
+        .respond_with(ResponseTemplate::new(200))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    client.create_bucket("test-bucket").await.unwrap();
+}
+
+// 2. delete_bucket — DELETE /{bucket}
+#[tokio::test]
+async fn delete_bucket_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("DELETE"))
+        .and(path("/test-bucket"))
+        .respond_with(ResponseTemplate::new(204))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    client.delete_bucket("test-bucket").await.unwrap();
+}
+
+// 3. list_buckets — GET /
+#[tokio::test]
+async fn list_buckets_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/"))
+        .respond_with(
+            ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "Buckets": [
+                    {"Name": "bucket-a", "CreationDate": "2025-01-01T00:00:00Z"},
+                    {"Name": "bucket-b", "CreationDate": "2025-06-15T12:00:00Z"}
+                ],
+                "Owner": {"ID": "owner-1", "DisplayName": "TestOwner"}
+            })),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let resp = client.list_buckets().await.unwrap();
+    assert_eq!(resp.buckets.len(), 2);
+    assert_eq!(resp.buckets[0].name, "bucket-a");
+    assert_eq!(resp.buckets[1].name, "bucket-b");
+    let owner = resp.owner.unwrap();
+    assert_eq!(owner.display_name, Some("TestOwner".to_string()));
+}
+
+#[tokio::test]
+async fn list_buckets_error_500() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/"))
+        .respond_with(ResponseTemplate::new(500).set_body_string("Internal Server Error"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let err = client.list_buckets().await.unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("500"), "expected 500 in error, got: {msg}");
+}
+
+#[tokio::test]
+async fn list_buckets_empty() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/"))
+        .respond_with(
+            ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "Buckets": [],
+            })),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let resp = client.list_buckets().await.unwrap();
+    assert!(resp.buckets.is_empty());
+}
+
+// 4. head_bucket — HEAD /{bucket}
+#[tokio::test]
+async fn head_bucket_exists() {
+    let server = MockServer::start().await;
+    Mock::given(method("HEAD"))
+        .and(path("/test-bucket"))
+        .respond_with(ResponseTemplate::new(200))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    assert!(client.head_bucket("test-bucket").await.unwrap());
+}
+
+#[tokio::test]
+async fn head_bucket_not_found() {
+    let server = MockServer::start().await;
+    Mock::given(method("HEAD"))
+        .and(path("/no-such-bucket"))
+        .respond_with(ResponseTemplate::new(404))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    assert!(!client.head_bucket("no-such-bucket").await.unwrap());
+}
+
+#[tokio::test]
+async fn head_bucket_403_returns_false() {
+    let server = MockServer::start().await;
+    Mock::given(method("HEAD"))
+        .and(path("/forbidden-bucket"))
+        .respond_with(ResponseTemplate::new(403))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    assert!(!client.head_bucket("forbidden-bucket").await.unwrap());
+}
+
+// 5. set_versioning — PUT /{bucket}?versioning
+#[tokio::test]
+async fn set_versioning_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket"))
+        .and(query_param("versioning", ""))
+        .respond_with(ResponseTemplate::new(200))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let body = serde_json::json!({"Status": "Enabled"});
+    client.set_versioning("test-bucket", &body).await.unwrap();
+}
+
+// 6. set_lifecycle — PUT /{bucket}?lifecycle
+#[tokio::test]
+async fn set_lifecycle_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket"))
+        .and(query_param("lifecycle", ""))
+        .respond_with(ResponseTemplate::new(200))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let body = serde_json::json!({"Rules": [{"Status": "Enabled"}]});
+    client.set_lifecycle("test-bucket", &body).await.unwrap();
+}
+
+// 7. set_cors — PUT /{bucket}?cors
+#[tokio::test]
+async fn set_cors_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket"))
+        .and(query_param("cors", ""))
+        .respond_with(ResponseTemplate::new(200))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let body = serde_json::json!({"CORSRules": [{"AllowedOrigins": ["*"]}]});
+    client.set_cors("test-bucket", &body).await.unwrap();
+}
+
+// 8. get_acl — GET /{bucket}?acl
+#[tokio::test]
+async fn get_acl_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/test-bucket"))
+        .and(query_param("acl", ""))
+        .respond_with(
+            ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "Owner": {"ID": "owner-1"},
+                "Grants": [{"Permission": "FULL_CONTROL"}]
+            })),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let acl = client.get_acl("test-bucket").await.unwrap();
+    assert_eq!(acl["Owner"]["ID"], "owner-1");
+    assert_eq!(acl["Grants"][0]["Permission"], "FULL_CONTROL");
+}
+
+// 9. set_policy — PUT /{bucket}?policy
+#[tokio::test]
+async fn set_policy_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket"))
+        .and(query_param("policy", ""))
+        .respond_with(ResponseTemplate::new(200))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let body = serde_json::json!({
+        "Version": "2012-10-17",
+        "Statement": [{"Effect": "Allow", "Principal": "*", "Action": "s3:GetObject"}]
+    });
+    client.set_policy("test-bucket", &body).await.unwrap();
+}
+
+// ===========================================================================
+// Object operations
+// ===========================================================================
+
+// 10. put_object — PUT /{bucket}/{key}
+#[tokio::test]
+async fn put_object_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket/hello.txt"))
+        .respond_with(ResponseTemplate::new(200))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    client
+        .put_object("test-bucket", "hello.txt", "text/plain", bytes::Bytes::from("hello world"))
+        .await
+        .unwrap();
+}
+
+#[tokio::test]
+async fn put_object_error_403() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket/secret.txt"))
+        .respond_with(ResponseTemplate::new(403).set_body_string("Access Denied"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let err = client
+        .put_object("test-bucket", "secret.txt", "text/plain", bytes::Bytes::from("nope"))
+        .await
+        .unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("403"), "expected 403 in error, got: {msg}");
+}
+
+#[tokio::test]
+async fn put_object_error_500() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket/fail.txt"))
+        .respond_with(ResponseTemplate::new(500).set_body_string("Internal Server Error"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let err = client
+        .put_object("test-bucket", "fail.txt", "text/plain", bytes::Bytes::from("data"))
+        .await
+        .unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("500"), "expected 500 in error, got: {msg}");
+}
+
+// 11. get_object — GET /{bucket}/{key}
+#[tokio::test]
+async fn get_object_success() {
+    let server = MockServer::start().await;
+    let payload = b"file contents here";
+    Mock::given(method("GET"))
+        .and(path("/test-bucket/hello.txt"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(payload.to_vec()))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let data = client.get_object("test-bucket", "hello.txt").await.unwrap();
+    assert_eq!(data.as_ref(), payload);
+}
+
+#[tokio::test]
+async fn get_object_error_404() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/test-bucket/missing.txt"))
+        .respond_with(ResponseTemplate::new(404).set_body_string("NoSuchKey"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let err = client.get_object("test-bucket", "missing.txt").await.unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("404"), "expected 404 in error, got: {msg}");
+}
+
+#[tokio::test]
+async fn get_object_error_500() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/test-bucket/broken.txt"))
+        .respond_with(ResponseTemplate::new(500).set_body_string("Internal Server Error"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let err = client.get_object("test-bucket", "broken.txt").await.unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("500"), "expected 500 in error, got: {msg}");
+}
+
+// 12. head_object — HEAD /{bucket}/{key}
+#[tokio::test]
+async fn head_object_exists() {
+    let server = MockServer::start().await;
+    Mock::given(method("HEAD"))
+        .and(path("/test-bucket/hello.txt"))
+        .respond_with(ResponseTemplate::new(200))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    assert!(client.head_object("test-bucket", "hello.txt").await.unwrap());
+}
+
+#[tokio::test]
+async fn head_object_not_found() {
+    let server = MockServer::start().await;
+    Mock::given(method("HEAD"))
+        .and(path("/test-bucket/missing.txt"))
+        .respond_with(ResponseTemplate::new(404))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    assert!(!client.head_object("test-bucket", "missing.txt").await.unwrap());
+}
+
+// 13. delete_object — DELETE /{bucket}/{key}
+#[tokio::test]
+async fn delete_object_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("DELETE"))
+        .and(path("/test-bucket/hello.txt"))
+        .respond_with(ResponseTemplate::new(204))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    client.delete_object("test-bucket", "hello.txt").await.unwrap();
+}
+
+// 14. copy_object — PUT /{bucket}/{key} with x-amz-copy-source header
+#[tokio::test]
+async fn copy_object_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/dest-bucket/dest-key"))
+        .and(wiremock::matchers::header("x-amz-copy-source", "/src-bucket/src-key"))
+        .respond_with(ResponseTemplate::new(200))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    client
+        .copy_object("dest-bucket", "dest-key", "/src-bucket/src-key")
+        .await
+        .unwrap();
+}
+
+#[tokio::test]
+async fn copy_object_error_403() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/dest-bucket/dest-key"))
+        .respond_with(ResponseTemplate::new(403).set_body_string("Access Denied"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let err = client
+        .copy_object("dest-bucket", "dest-key", "/src-bucket/src-key")
+        .await
+        .unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("403"), "expected 403 in error, got: {msg}");
+}
+
+// 15. list_objects_v2 — GET /{bucket}?list-type=2
+#[tokio::test]
+async fn list_objects_v2_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/test-bucket"))
+        .and(query_param("list-type", "2"))
+        .respond_with(
+            ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "Name": "test-bucket",
+                "Prefix": null,
+                "MaxKeys": 1000,
+                "IsTruncated": false,
+                "Contents": [
+                    {
+                        "Key": "file1.txt",
+                        "LastModified": "2025-01-01T00:00:00Z",
+                        "ETag": "\"abc123\"",
+                        "Size": 1024,
+                        "StorageClass": "STANDARD"
+                    },
+                    {
+                        "Key": "file2.txt",
+                        "Size": 2048
+                    }
+                ]
+            })),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let resp = client.list_objects_v2("test-bucket", None, None).await.unwrap();
+    assert_eq!(resp.name, "test-bucket");
+    assert_eq!(resp.contents.len(), 2);
+    assert_eq!(resp.contents[0].key, "file1.txt");
+    assert_eq!(resp.contents[0].size, Some(1024));
+    assert_eq!(resp.contents[1].key, "file2.txt");
+    assert_eq!(resp.is_truncated, Some(false));
+}
+
+#[tokio::test]
+async fn list_objects_v2_with_prefix_and_max_keys() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/test-bucket"))
+        .and(query_param("list-type", "2"))
+        .and(query_param("prefix", "docs/"))
+        .and(query_param("max-keys", "10"))
+        .respond_with(
+            ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "Name": "test-bucket",
+                "Prefix": "docs/",
+                "MaxKeys": 10,
+                "IsTruncated": false,
+                "Contents": [
+                    {"Key": "docs/readme.md", "Size": 512}
+                ]
+            })),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let resp = client
+        .list_objects_v2("test-bucket", Some("docs/"), Some(10))
+        .await
+        .unwrap();
+    assert_eq!(resp.prefix, Some("docs/".to_string()));
+    assert_eq!(resp.max_keys, Some(10));
+    assert_eq!(resp.contents.len(), 1);
+    assert_eq!(resp.contents[0].key, "docs/readme.md");
+}
+
+// 16. set_tags — PUT /{bucket}/{key}?tagging
+#[tokio::test]
+async fn set_tags_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket/hello.txt"))
+        .and(query_param("tagging", ""))
+        .respond_with(ResponseTemplate::new(200))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let body = serde_json::json!({"TagSet": [{"Key": "env", "Value": "prod"}]});
+    client.set_tags("test-bucket", "hello.txt", &body).await.unwrap();
+}
+
+// 17. get_tags — GET /{bucket}/{key}?tagging
+#[tokio::test]
+async fn get_tags_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/test-bucket/hello.txt"))
+        .and(query_param("tagging", ""))
+        .respond_with(
+            ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "TagSet": [{"Key": "env", "Value": "prod"}]
+            })),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let tags = client.get_tags("test-bucket", "hello.txt").await.unwrap();
+    assert_eq!(tags["TagSet"][0]["Key"], "env");
+    assert_eq!(tags["TagSet"][0]["Value"], "prod");
+}
+
+// ===========================================================================
+// Multipart operations
+// ===========================================================================
+
+// 18. initiate_multipart — POST /{bucket}/{key}?uploads
+#[tokio::test]
+async fn initiate_multipart_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/test-bucket/large-file.bin"))
+        .and(query_param("uploads", ""))
+        .respond_with(
+            ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "Bucket": "test-bucket",
+                "Key": "large-file.bin",
+                "UploadId": "upload-abc-123"
+            })),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let resp = client.initiate_multipart("test-bucket", "large-file.bin").await.unwrap();
+    assert_eq!(resp.bucket, "test-bucket");
+    assert_eq!(resp.key, "large-file.bin");
+    assert_eq!(resp.upload_id, "upload-abc-123");
+}
+
+// 19. upload_part — PUT /{bucket}/{key}?partNumber=N&uploadId=xxx
+#[tokio::test]
+async fn upload_part_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket/large-file.bin"))
+        .and(query_param("partNumber", "1"))
+        .and(query_param("uploadId", "upload-abc-123"))
+        .respond_with(
+            ResponseTemplate::new(200)
+                .append_header("ETag", "\"part-etag-1\""),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let resp = client
+        .upload_part(
+            "test-bucket",
+            "large-file.bin",
+            "upload-abc-123",
+            1,
+            bytes::Bytes::from("part data chunk 1"),
+        )
+        .await
+        .unwrap();
+    assert_eq!(resp.etag, "\"part-etag-1\"");
+    assert_eq!(resp.part_number, 1);
+}
+
+#[tokio::test]
+async fn upload_part_error_500() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket/large-file.bin"))
+        .and(query_param("partNumber", "2"))
+        .and(query_param("uploadId", "upload-abc-123"))
+        .respond_with(ResponseTemplate::new(500).set_body_string("Internal Server Error"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let err = client
+        .upload_part(
+            "test-bucket",
+            "large-file.bin",
+            "upload-abc-123",
+            2,
+            bytes::Bytes::from("data"),
+        )
+        .await
+        .unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("500"), "expected 500 in error, got: {msg}");
+}
+
+#[tokio::test]
+async fn upload_part_no_etag_header() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket/large-file.bin"))
+        .and(query_param("partNumber", "3"))
+        .and(query_param("uploadId", "upload-abc-123"))
+        .respond_with(ResponseTemplate::new(200))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let resp = client
+        .upload_part(
+            "test-bucket",
+            "large-file.bin",
+            "upload-abc-123",
+            3,
+            bytes::Bytes::from("data"),
+        )
+        .await
+        .unwrap();
+    // No ETag header → empty string fallback
+    assert_eq!(resp.etag, "");
+    assert_eq!(resp.part_number, 3);
+}
+
+// 20. complete_multipart — POST /{bucket}/{key}?uploadId=xxx
+#[tokio::test]
+async fn complete_multipart_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/test-bucket/large-file.bin"))
+        .and(query_param("uploadId", "upload-abc-123"))
+        .respond_with(
+            ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "Location": "https://s3.example.com/test-bucket/large-file.bin",
+                "Bucket": "test-bucket",
+                "Key": "large-file.bin",
+                "ETag": "\"final-etag-xyz\""
+            })),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let parts = serde_json::json!({
+        "Parts": [
+            {"PartNumber": 1, "ETag": "\"part-etag-1\""},
+            {"PartNumber": 2, "ETag": "\"part-etag-2\""}
+        ]
+    });
+    let resp = client
+        .complete_multipart("test-bucket", "large-file.bin", "upload-abc-123", &parts)
+        .await
+        .unwrap();
+    assert_eq!(resp.bucket, "test-bucket");
+    assert_eq!(resp.key, "large-file.bin");
+    assert_eq!(resp.etag, Some("\"final-etag-xyz\"".to_string()));
+    assert_eq!(
+        resp.location,
+        Some("https://s3.example.com/test-bucket/large-file.bin".to_string())
+    );
+}
+
+// 21. abort_multipart — DELETE /{bucket}/{key}?uploadId=xxx
+#[tokio::test]
+async fn abort_multipart_success() {
+    let server = MockServer::start().await;
+    Mock::given(method("DELETE"))
+        .and(path("/test-bucket/large-file.bin"))
+        .and(query_param("uploadId", "upload-abc-123"))
+        .respond_with(ResponseTemplate::new(204))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    client
+        .abort_multipart("test-bucket", "large-file.bin", "upload-abc-123")
+        .await
+        .unwrap();
+}
+
+// ===========================================================================
+// Additional error paths
+// ===========================================================================
+
+#[tokio::test]
+async fn create_bucket_error_409_conflict() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/existing-bucket"))
+        .respond_with(ResponseTemplate::new(409).set_body_string("BucketAlreadyExists"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let err = client.create_bucket("existing-bucket").await.unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("409"), "expected 409 in error, got: {msg}");
+}
+
+#[tokio::test]
+async fn delete_bucket_error_404() {
+    let server = MockServer::start().await;
+    Mock::given(method("DELETE"))
+        .and(path("/no-such-bucket"))
+        .respond_with(ResponseTemplate::new(404).set_body_string("NoSuchBucket"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let err = client.delete_bucket("no-such-bucket").await.unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("404"), "expected 404 in error, got: {msg}");
+}
+
+#[tokio::test]
+async fn delete_object_error_403() {
+    let server = MockServer::start().await;
+    Mock::given(method("DELETE"))
+        .and(path("/test-bucket/protected.txt"))
+        .respond_with(ResponseTemplate::new(403).set_body_string("Access Denied"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let err = client.delete_object("test-bucket", "protected.txt").await.unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("403"), "expected 403 in error, got: {msg}");
+}
+
+#[tokio::test]
+async fn get_acl_error_403() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/test-bucket"))
+        .and(query_param("acl", ""))
+        .respond_with(ResponseTemplate::new(403).set_body_string("Access Denied"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let err = client.get_acl("test-bucket").await.unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("403"), "expected 403 in error, got: {msg}");
+}
+
+#[tokio::test]
+async fn set_versioning_error_403() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/test-bucket"))
+        .and(query_param("versioning", ""))
+        .respond_with(ResponseTemplate::new(403).set_body_string("Access Denied"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let body = serde_json::json!({"Status": "Enabled"});
+    let err = client.set_versioning("test-bucket", &body).await.unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("403"), "expected 403 in error, got: {msg}");
+}
+
+#[tokio::test]
+async fn copy_object_error_500() {
+    let server = MockServer::start().await;
+    Mock::given(method("PUT"))
+        .and(path("/dest-bucket/dest-key"))
+        .respond_with(ResponseTemplate::new(500).set_body_string("InternalError"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = mock_client(&server);
+    let err = client
+        .copy_object("dest-bucket", "dest-key", "/src-bucket/src-key")
+        .await
+        .unwrap_err();
+    let msg = err.to_string();
+    assert!(msg.contains("500"), "expected 500 in error, got: {msg}");
+}
+
+// ===========================================================================
+// Client construction (kept from original)
+// ===========================================================================
+
+#[tokio::test]
+async fn client_from_parts() {
+    let client = S3Client::from_parts(MINIO_URL.into(), AuthMethod::None);
+    assert_eq!(client.base_url(), MINIO_URL);
+    assert_eq!(client.service_name(), "s3");
+}
+
+#[tokio::test]
+async fn client_connect_builds_url() {
+    let client = S3Client::connect("example.com");
+    assert_eq!(client.base_url(), "https://s3.example.com");
+}
+
+#[tokio::test]
+async fn client_set_auth_does_not_panic() {
+    let mut client = S3Client::from_parts(MINIO_URL.into(), AuthMethod::None);
+    client.set_auth(AuthMethod::Bearer("tok".into()));
+    assert_eq!(client.base_url(), MINIO_URL);
+}