oleanderhq-sdk 0.1.0__tar.gz

oleanderhq_sdk-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/

oleanderhq_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: oleanderhq-sdk
+Version: 0.1.0
+Summary: Python SDK for oleander: query lake, list and launch Spark jobs
+License-Expression: MIT
+Keywords: data,lake,oleander,openLineage,query,sdk,spark
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: respx<1,>=0.22; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# oleander Python SDK
+
+Use the [oleander](https://oleander.dev) API from Python: run lake queries, list Spark jobs, and launch Spark jobs.
+
+## Install
+
+```bash
+pip install oleanderhq-sdk
+```
+
+## Get your API key
+
+Create an API key in [oleander settings](https://oleander.dev/app/settings), or run `oleander configure` if you use the CLI. You can pass the key when creating the client or set the `OLEANDER_API_KEY` environment variable.
+
+## Quick start
+
+```python
+import asyncio
+from oleander_sdk import Oleander
+
+async def main():
+    oleander = Oleander()
+    result = await oleander.list_spark_jobs()
+    print(result.scripts)
+
+asyncio.run(main())
+```
+
+## API
+
+All methods are async. Use `await` when calling them.
+
+### Query (lake)
+
+Run a SQL query against the oleander lake. The second parameter is optional; `save` defaults to `False`. Use `save=True` to persist results as a table.
+
+```python
+from oleander_sdk import Oleander, QueryOptions
+
+oleander = Oleander()
+result = await oleander.query(
+    "SELECT * FROM public.iris_dataset LIMIT 10",
+)
+print(result.results.columns, result.results.rows)
+print(result.row_count, result.execution_time)
+if result.saved_table_name:
+    print("Saved to:", result.saved_table_name)
+```
+
+### List Spark jobs
+
+Paginated list of your Spark job scripts. Options: `limit` (default 20), `offset` (default 0).
+
+```python
+from oleander_sdk import Oleander, ListSparkJobsOptions
+
+oleander = Oleander()
+result = await oleander.list_spark_jobs()
+print(result.scripts, result.has_more)
+
+next_page = await oleander.list_spark_jobs(ListSparkJobsOptions(offset=20))
+```
+
+### Launch Spark job
+
+Submit a Spark job. Required: `namespace`, `name`, `script_name`. Other options (e.g. `args`, machine types, tags) have defaults.
+
+```python
+from oleander_sdk import Oleander, SparkJobSubmitOptions
+
+oleander = Oleander()
+result = await oleander.submit_spark_job(SparkJobSubmitOptions(
+    namespace="my-namespace",
+    name="my-job-name",
+    script_name="my_script.py",
+))
+print("Run ID:", result.run_id)
+```
+
+### Wait for a run to finish
+
+Submit and poll until the run completes. Optional: `poll_interval_ms` (default 10000), `timeout_ms` (default 600000).
+
+```python
+from oleander_sdk import Oleander, SubmitSparkJobAndWaitOptions
+
+oleander = Oleander()
+result = await oleander.submit_spark_job_and_wait(SubmitSparkJobAndWaitOptions(
+    namespace="my-namespace",
+    name="my-job-name",
+    script_name="my_script.py",
+))
+print(result.run_id, result.state)  # COMPLETE | FAIL | ABORT
+```
+
+### Get run status
+
+```python
+run = await oleander.get_run(run_id)
+print(run.state, run.duration)
+```
+
+## Options
+
+- **Constructor**: `Oleander(api_key=..., base_url=...)`. Omit `api_key` to use `OLEANDER_API_KEY`. Set `base_url` to use a different endpoint (e.g. `http://localhost:3000`).
+- **Models**: The package exports Pydantic models (e.g. `OleanderOptions`, `SparkJobSubmitOptions`) if you want to validate config or options yourself.

oleanderhq_sdk-0.1.0/README.md

@@ -0,0 +1,106 @@
+# oleander Python SDK
+
+Use the [oleander](https://oleander.dev) API from Python: run lake queries, list Spark jobs, and launch Spark jobs.
+
+## Install
+
+```bash
+pip install oleanderhq-sdk
+```
+
+## Get your API key
+
+Create an API key in [oleander settings](https://oleander.dev/app/settings), or run `oleander configure` if you use the CLI. You can pass the key when creating the client or set the `OLEANDER_API_KEY` environment variable.
+
+## Quick start
+
+```python
+import asyncio
+from oleander_sdk import Oleander
+
+async def main():
+    oleander = Oleander()
+    result = await oleander.list_spark_jobs()
+    print(result.scripts)
+
+asyncio.run(main())
+```
+
+## API
+
+All methods are async. Use `await` when calling them.
+
+### Query (lake)
+
+Run a SQL query against the oleander lake. The second parameter is optional; `save` defaults to `False`. Use `save=True` to persist results as a table.
+
+```python
+from oleander_sdk import Oleander, QueryOptions
+
+oleander = Oleander()
+result = await oleander.query(
+    "SELECT * FROM public.iris_dataset LIMIT 10",
+)
+print(result.results.columns, result.results.rows)
+print(result.row_count, result.execution_time)
+if result.saved_table_name:
+    print("Saved to:", result.saved_table_name)
+```
+
+### List Spark jobs
+
+Paginated list of your Spark job scripts. Options: `limit` (default 20), `offset` (default 0).
+
+```python
+from oleander_sdk import Oleander, ListSparkJobsOptions
+
+oleander = Oleander()
+result = await oleander.list_spark_jobs()
+print(result.scripts, result.has_more)
+
+next_page = await oleander.list_spark_jobs(ListSparkJobsOptions(offset=20))
+```
+
+### Launch Spark job
+
+Submit a Spark job. Required: `namespace`, `name`, `script_name`. Other options (e.g. `args`, machine types, tags) have defaults.
+
+```python
+from oleander_sdk import Oleander, SparkJobSubmitOptions
+
+oleander = Oleander()
+result = await oleander.submit_spark_job(SparkJobSubmitOptions(
+    namespace="my-namespace",
+    name="my-job-name",
+    script_name="my_script.py",
+))
+print("Run ID:", result.run_id)
+```
+
+### Wait for a run to finish
+
+Submit and poll until the run completes. Optional: `poll_interval_ms` (default 10000), `timeout_ms` (default 600000).
+
+```python
+from oleander_sdk import Oleander, SubmitSparkJobAndWaitOptions
+
+oleander = Oleander()
+result = await oleander.submit_spark_job_and_wait(SubmitSparkJobAndWaitOptions(
+    namespace="my-namespace",
+    name="my-job-name",
+    script_name="my_script.py",
+))
+print(result.run_id, result.state)  # COMPLETE | FAIL | ABORT
+```
+
+### Get run status
+
+```python
+run = await oleander.get_run(run_id)
+print(run.state, run.duration)
+```
+
+## Options
+
+- **Constructor**: `Oleander(api_key=..., base_url=...)`. Omit `api_key` to use `OLEANDER_API_KEY`. Set `base_url` to use a different endpoint (e.g. `http://localhost:3000`).
+- **Models**: The package exports Pydantic models (e.g. `OleanderOptions`, `SparkJobSubmitOptions`) if you want to validate config or options yourself.

oleanderhq_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "oleanderhq-sdk"
+version = "0.1.0"
+description = "Python SDK for oleander: query lake, list and launch Spark jobs"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["oleander", "sdk", "lake", "spark", "query", "data", "openLineage"]
+dependencies = [
+    "httpx>=0.27,<1",
+    "pydantic>=2.7,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8,<9",
+    "pytest-asyncio>=0.24,<1",
+    "respx>=0.22,<1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oleander_sdk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

oleanderhq_sdk-0.1.0/src/oleander_sdk/__init__.py

@@ -0,0 +1,48 @@
+"""oleander Python SDK — query lake, list and launch Spark jobs."""
+
+from .client import Oleander, SubmitAndWaitResult
+from .models import (
+    ApiErrorBody,
+    DEFAULT_BASE_URL,
+    LakeQueryResult,
+    ListSparkJobsOptions,
+    ListSparkJobsResult,
+    OleanderOptions,
+    QueryOptions,
+    QueryResultColumns,
+    RunJobInfo,
+    RunPipelineInfo,
+    RunResponse,
+    RunState,
+    RunTag,
+    SparkJobListPage,
+    SparkJobRun,
+    SparkJobSubmitOptions,
+    SparkMachineType,
+    SubmitSparkJobAndWaitOptions,
+    TERMINAL_STATES,
+)
+
+__all__ = [
+    "Oleander",
+    "SubmitAndWaitResult",
+    "ApiErrorBody",
+    "DEFAULT_BASE_URL",
+    "LakeQueryResult",
+    "ListSparkJobsOptions",
+    "ListSparkJobsResult",
+    "OleanderOptions",
+    "QueryOptions",
+    "QueryResultColumns",
+    "RunJobInfo",
+    "RunPipelineInfo",
+    "RunResponse",
+    "RunState",
+    "RunTag",
+    "SparkJobListPage",
+    "SparkJobRun",
+    "SparkJobSubmitOptions",
+    "SparkMachineType",
+    "SubmitSparkJobAndWaitOptions",
+    "TERMINAL_STATES",
+]

oleanderhq_sdk-0.1.0/src/oleander_sdk/client.py

@@ -0,0 +1,244 @@
+"""Oleander API client (mirrors client.ts)."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+import httpx
+
+from .models import (
+    ApiErrorBody,
+    DEFAULT_BASE_URL,
+    LakeQueryResult,
+    ListSparkJobsOptions,
+    ListSparkJobsResult,
+    OleanderOptions,
+    QueryOptions,
+    RunResponse,
+    SparkJobRun,
+    SparkJobSubmitOptions,
+    SubmitSparkJobAndWaitOptions,
+    TERMINAL_STATES,
+)
+
+
+def _parse_error_body(body: dict, status: int) -> str:
+    try:
+        parsed = ApiErrorBody.model_validate(body)
+        return parsed.error or parsed.details or f"HTTP {status}"
+    except Exception:
+        return f"HTTP {status}"
+
+
+@dataclass
+class SubmitAndWaitResult:
+    """Result returned by :meth:`Oleander.submit_spark_job_and_wait`."""
+
+    run_id: str
+    state: str
+    run: RunResponse
+
+
+class Oleander:
+    """Oleander API client.
+
+    Mirrors the TypeScript SDK — query lake, list Spark jobs, and launch Spark
+    jobs.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ) -> None:
+        opts = OleanderOptions(
+            api_key=api_key,
+            **({"base_url": base_url} if base_url is not None else {}),
+        )
+
+        resolved_key = (opts.api_key or "").strip() or os.environ.get(
+            "OLEANDER_API_KEY", ""
+        )
+        if not resolved_key:
+            raise ValueError(
+                "Oleander requires a non-empty api_key (or set OLEANDER_API_KEY)"
+            )
+
+        self._api_key = resolved_key
+        self._base_url = (opts.base_url or DEFAULT_BASE_URL).strip().rstrip("/")
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _headers(self, *, content_type: bool = True) -> dict[str, str]:
+        h: dict[str, str] = {"Authorization": f"Bearer {self._api_key}"}
+        if content_type:
+            h["Content-Type"] = "application/json"
+        return h
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[dict] = None,
+        params: Optional[dict[str, str]] = None,
+        content_type: bool = True,
+    ) -> dict:
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            resp = await client.request(
+                method,
+                f"{self._base_url}{path}",
+                headers=self._headers(content_type=content_type),
+                json=json,
+                params=params,
+            )
+        try:
+            body = resp.json()
+        except Exception:
+            body = {}
+        if resp.status_code >= 400:
+            raise RuntimeError(_parse_error_body(body, resp.status_code))
+        return body
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def query(
+        self,
+        sql: str,
+        options: Optional[QueryOptions] = None,
+    ) -> LakeQueryResult:
+        """Execute a lake query (mirrors ``oleander query``)."""
+        q = (sql or "").strip()
+        if not q:
+            raise ValueError("Query is required")
+        opts = options or QueryOptions()
+
+        raw = await self._request(
+            "POST",
+            "/api/v1/warehouse/query",
+            json={"query": q, "autoSaveByHash": opts.save},
+        )
+
+        result = LakeQueryResult.model_validate(raw)
+        if not result.success and result.error:
+            raise RuntimeError(result.details or result.error)
+        return result
+
+    async def list_spark_jobs(
+        self,
+        options: Optional[ListSparkJobsOptions] = None,
+    ) -> ListSparkJobsResult:
+        """List spark jobs (mirrors ``oleander spark jobs list``).
+
+        Uses limit/offset pagination; pages through the API internally.
+        """
+        opts = options or ListSparkJobsOptions()
+        limit, offset = opts.limit, opts.offset
+
+        all_scripts: list[str] = []
+        continuation_token: Optional[str] = None
+
+        while True:
+            params: Optional[dict[str, str]] = None
+            if continuation_token:
+                params = {"continuationToken": continuation_token}
+
+            raw = await self._request(
+                "GET",
+                "/api/v1/spark/scripts",
+                params=params,
+                content_type=False,
+            )
+
+            scripts = raw.get("scripts", [])
+            all_scripts.extend(scripts)
+            continuation_token = raw.get("continuationToken")
+            if not continuation_token or len(all_scripts) >= offset + limit:
+                break
+
+        sliced = all_scripts[offset : offset + limit]
+        has_more = bool(continuation_token) or len(all_scripts) > offset + limit
+        return ListSparkJobsResult(scripts=sliced, has_more=has_more)
+
+    async def submit_spark_job(
+        self,
+        options: SparkJobSubmitOptions,
+    ) -> SparkJobRun:
+        """Submit a spark job (mirrors ``oleander spark jobs submit``).
+
+        Returns the run ID; use :meth:`get_run` or
+        :meth:`submit_spark_job_and_wait` to poll status.
+        """
+        raw = await self._request(
+            "POST",
+            "/api/v1/spark/jobs",
+            json={
+                "namespace": options.namespace.strip(),
+                "name": options.name.strip(),
+                "scriptName": options.script_name.strip(),
+                "arguments": options.args,
+                "driverMachineType": options.driver_machine_type.value,
+                "executorMachineType": options.executor_machine_type.value,
+                "executorNumbers": options.executor_numbers,
+                "jobTags": options.job_tags,
+                "runTags": options.run_tags,
+            },
+        )
+        return SparkJobRun.model_validate(raw)
+
+    async def get_run(self, run_id: str) -> RunResponse:
+        """Get run status (used for polling after submit)."""
+        if not run_id or not run_id.strip():
+            raise ValueError("run_id is required")
+
+        raw = await self._request(
+            "GET",
+            f"/api/v2/runs/{run_id}",
+            content_type=False,
+        )
+        return RunResponse.model_validate(raw)
+
+    async def submit_spark_job_and_wait(
+        self,
+        options: SubmitSparkJobAndWaitOptions,
+    ) -> SubmitAndWaitResult:
+        """Submit a spark job and wait until the run reaches a terminal state
+        (COMPLETE, FAIL, ABORT).
+        """
+        submit_opts = SparkJobSubmitOptions(
+            namespace=options.namespace,
+            name=options.name,
+            script_name=options.script_name,
+            args=options.args,
+            driver_machine_type=options.driver_machine_type,
+            executor_machine_type=options.executor_machine_type,
+            executor_numbers=options.executor_numbers,
+            job_tags=options.job_tags,
+            run_tags=options.run_tags,
+        )
+        result = await self.submit_spark_job(submit_opts)
+        run_id = result.run_id
+        poll_interval_s = options.poll_interval_ms / 1000.0
+        timeout_s = options.timeout_ms / 1000.0
+        started = time.monotonic()
+
+        while time.monotonic() - started < timeout_s:
+            run = await self.get_run(run_id)
+            state = run.state or ""
+            if state in TERMINAL_STATES:
+                return SubmitAndWaitResult(run_id=run_id, state=state, run=run)
+            await asyncio.sleep(poll_interval_s)
+
+        run = await self.get_run(run_id)
+        raise TimeoutError(
+            f"Timeout waiting for run {run_id} (state: {run.state or 'unknown'})"
+        )

oleanderhq_sdk-0.1.0/src/oleander_sdk/models.py

@@ -0,0 +1,165 @@
+"""Pydantic models for the oleander SDK (mirrors schemas.ts)."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# Spark machine types
+# ---------------------------------------------------------------------------
+
+class SparkMachineType(str, Enum):
+    SPARK_1_C = "spark.1.c"
+    SPARK_2_C = "spark.2.c"
+    SPARK_4_C = "spark.4.c"
+    SPARK_8_C = "spark.8.c"
+    SPARK_16_C = "spark.16.c"
+    SPARK_1_B = "spark.1.b"
+    SPARK_2_B = "spark.2.b"
+    SPARK_4_B = "spark.4.b"
+    SPARK_8_B = "spark.8.b"
+    SPARK_16_B = "spark.16.b"
+    SPARK_1_M = "spark.1.m"
+    SPARK_2_M = "spark.2.m"
+    SPARK_4_M = "spark.4.m"
+    SPARK_8_M = "spark.8.m"
+    SPARK_16_M = "spark.16.m"
+
+
+# ---------------------------------------------------------------------------
+# API error
+# ---------------------------------------------------------------------------
+
+class ApiErrorBody(BaseModel):
+    error: Optional[str] = None
+    details: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Constructor options
+# ---------------------------------------------------------------------------
+
+DEFAULT_BASE_URL = "https://oleander.dev"
+
+
+class OleanderOptions(BaseModel):
+    api_key: Optional[str] = None
+    base_url: str = DEFAULT_BASE_URL
+
+
+# ---------------------------------------------------------------------------
+# Query
+# ---------------------------------------------------------------------------
+
+class QueryOptions(BaseModel):
+    save: bool = False
+
+
+class QueryResultColumns(BaseModel):
+    columns: list[str]
+    column_types: list[str]
+    rows: list[list[Any]]
+
+
+class LakeQueryResult(BaseModel):
+    success: bool
+    results: Optional[QueryResultColumns] = None
+    row_count: Optional[int] = None
+    execution_time: Optional[str] = None
+    saved_table_name: Optional[str] = None
+    error: Optional[str] = None
+    details: Optional[str] = None
+    query: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Spark job list
+# ---------------------------------------------------------------------------
+
+class SparkJobListPage(BaseModel):
+    scripts: list[str]
+    continuation_token: Optional[str] = Field(None, alias="continuationToken")
+
+    model_config = {"populate_by_name": True}
+
+
+class ListSparkJobsOptions(BaseModel):
+    limit: int = Field(default=20, gt=0)
+    offset: int = Field(default=0, ge=0)
+
+
+class ListSparkJobsResult(BaseModel):
+    scripts: list[str]
+    has_more: bool
+
+
+# ---------------------------------------------------------------------------
+# Spark job submit
+# ---------------------------------------------------------------------------
+
+class SparkJobSubmitOptions(BaseModel):
+    namespace: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    script_name: str = Field(min_length=1)
+    args: list[str] = Field(default_factory=list)
+    driver_machine_type: SparkMachineType = SparkMachineType.SPARK_1_B
+    executor_machine_type: SparkMachineType = SparkMachineType.SPARK_1_B
+    executor_numbers: int = Field(default=2, ge=1, le=20)
+    job_tags: list[str] = Field(default_factory=list)
+    run_tags: list[str] = Field(default_factory=list)
+
+
+class SubmitSparkJobAndWaitOptions(SparkJobSubmitOptions):
+    poll_interval_ms: int = Field(default=10_000, gt=0)
+    timeout_ms: int = Field(default=600_000, gt=0)
+
+
+class SparkJobRun(BaseModel):
+    run_id: str = Field(alias="runId")
+
+    model_config = {"populate_by_name": True}
+
+
+# ---------------------------------------------------------------------------
+# Run status
+# ---------------------------------------------------------------------------
+
+RunState = Literal["COMPLETE", "FAIL", "ABORT"]
+
+TERMINAL_STATES: set[str] = {"COMPLETE", "FAIL", "ABORT"}
+
+
+class RunTag(BaseModel):
+    key: str
+    value: str
+    source: Optional[str] = None
+
+
+class RunJobInfo(BaseModel):
+    id: str
+    name: str
+    namespace: str
+
+
+class RunPipelineInfo(BaseModel):
+    id: str
+    name: str
+    namespace: str
+
+
+class RunResponse(BaseModel):
+    id: str
+    state: Optional[str] = None
+    started_at: Optional[str] = None
+    queued_at: Optional[str] = None
+    scheduled_at: Optional[str] = None
+    ended_at: Optional[str] = None
+    duration: Optional[float] = None
+    error: Optional[Any] = None
+    tags: list[RunTag]
+    job: RunJobInfo
+    pipeline: RunPipelineInfo

oleanderhq_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,115 @@
+"""Tests for the oleander Python SDK.
+
+Integration tests (list_spark_jobs, query) run only when OLEANDER_API_KEY is set.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from oleander_sdk import (
+    Oleander,
+    OleanderOptions,
+    SparkJobSubmitOptions,
+    SparkMachineType,
+)
+
+
+# ---------------------------------------------------------------------------
+# Unit tests
+# ---------------------------------------------------------------------------
+
+
+class TestOleanderConstructor:
+    def test_throws_when_api_key_missing_and_env_unset(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("OLEANDER_API_KEY", raising=False)
+        with pytest.raises(ValueError, match="Oleander requires a non-empty api_key"):
+            Oleander()
+
+    def test_accepts_api_key(self) -> None:
+        oleander = Oleander(api_key="test-key")
+        assert oleander is not None
+
+    def test_uses_env_api_key(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("OLEANDER_API_KEY", "env-key")
+        oleander = Oleander()
+        assert oleander._api_key == "env-key"
+
+    def test_constructor_api_key_takes_precedence(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("OLEANDER_API_KEY", "env-key")
+        oleander = Oleander(api_key="explicit-key")
+        assert oleander._api_key == "explicit-key"
+
+    def test_custom_base_url(self) -> None:
+        oleander = Oleander(api_key="k", base_url="https://custom.example.com/")
+        assert oleander._base_url == "https://custom.example.com"
+
+
+class TestOleanderOptions:
+    def test_parses_valid_options(self) -> None:
+        opts = OleanderOptions(api_key="k", base_url="https://x.com")
+        assert opts.api_key == "k"
+        assert opts.base_url == "https://x.com"
+
+    def test_allows_optional_api_key(self) -> None:
+        opts = OleanderOptions()
+        assert opts.api_key is None
+
+
+class TestSubmitOptionsSchema:
+    def test_parses_minimal_options_with_defaults(self) -> None:
+        opts = SparkJobSubmitOptions(
+            namespace="ns",
+            name="job",
+            script_name="main.py",
+        )
+        assert opts.namespace == "ns"
+        assert opts.name == "job"
+        assert opts.script_name == "main.py"
+        assert opts.args == []
+        assert opts.driver_machine_type == SparkMachineType.SPARK_1_B
+        assert opts.executor_numbers == 2
+
+    def test_rejects_missing_required_fields(self) -> None:
+        with pytest.raises(Exception):
+            SparkJobSubmitOptions(namespace="ns", name="j")  # type: ignore[call-arg]
+        with pytest.raises(Exception):
+            SparkJobSubmitOptions(namespace="ns", script_name="x.py")  # type: ignore[call-arg]
+
+
+# ---------------------------------------------------------------------------
+# Integration tests — only run when OLEANDER_API_KEY is set
+# ---------------------------------------------------------------------------
+
+_has_api_key = bool(os.environ.get("OLEANDER_API_KEY"))
+skip_without_key = pytest.mark.skipif(not _has_api_key, reason="OLEANDER_API_KEY not set")
+
+
+@skip_without_key
+class TestListSparkJobsIntegration:
+    async def test_returns_shape(self) -> None:
+        from oleander_sdk import ListSparkJobsOptions
+
+        oleander = Oleander()
+        result = await oleander.list_spark_jobs(ListSparkJobsOptions(limit=5, offset=0))
+        assert isinstance(result.scripts, list)
+        assert isinstance(result.has_more, bool)
+
+
+@skip_without_key
+class TestQueryIntegration:
+    async def test_returns_shape(self) -> None:
+        from oleander_sdk import QueryOptions
+
+        oleander = Oleander()
+        result = await oleander.query(
+            "SELECT * FROM public.iris_dataset LIMIT 10",
+            QueryOptions(save=False),
+        )
+        assert result.success is True
+        assert result.results is not None
+        assert result.row_count is not None
+        assert result.execution_time is not None
+        assert result.saved_table_name is None