northstar-sdk 1.0__py3-none-any.whl

northstar_sdk/__init__.py

@@ -0,0 +1,44 @@
+"""
+northstar-sdk — thin HTTP client for the Northstar platform API.
+
+Use :class:`Client` as the single entry point::
+
+    from northstar_sdk import Client
+
+    client = Client()
+    kpi = client.kpis.create(name="...", dataset_id="...", definition_type="MANUAL")
+    kpi.assign_to_team("analytics")
+
+Catalogue records and resource handles live under ``client.*`` namespaces.
+Optional: ``from northstar_sdk.catalogue import KpiRecord, NotFoundError``.
+"""
+
+from northstar_sdk.catalogue import (
+    AmbiguousLookupError,
+    CatalogueError,
+    NotFoundError,
+    Page,
+)
+from northstar_sdk.client import Client
+from northstar_sdk.orchestration import (
+    OrchestrationHooks,
+    orchestration_hooks,
+    send_orchestration_event,
+    send_workflow_event,
+    sync_workflow_configs,
+    northstar_flow,
+)
+
+__all__ = [
+    "AmbiguousLookupError",
+    "CatalogueError",
+    "Client",
+    "NotFoundError",
+    "OrchestrationHooks",
+    "Page",
+    "orchestration_hooks",
+    "send_orchestration_event",
+    "send_workflow_event",
+    "sync_workflow_configs",
+    "northstar_flow",
+]

northstar_sdk/catalogue/__init__.py

@@ -0,0 +1,46 @@
+"""Read-only catalogue queries against the Northstar platform API."""
+
+from northstar_sdk.catalogue.dashboard_folders import DashboardFolderCatalogue
+from northstar_sdk.catalogue.dashboards import (
+    DashboardBrowsePage,
+    DashboardCatalogue,
+    DashboardFolderRecord,
+    DashboardRecord,
+)
+from northstar_sdk.catalogue.data_sources import DataSourceCatalogue, DataSourceRecord
+from northstar_sdk.catalogue.datasets import DatasetCatalogue, DatasetRecord
+from northstar_sdk.catalogue.exceptions import (
+    AmbiguousLookupError,
+    CatalogueError,
+    NotFoundError,
+)
+from northstar_sdk.catalogue.figures import FigureCatalogue, FigureRecord
+from northstar_sdk.catalogue.kpis import KpiCatalogue, KpiRecord
+from northstar_sdk.catalogue.page import Page
+from northstar_sdk.catalogue.search import GlobalSearch, SearchGroup, SearchItem
+from northstar_sdk.catalogue.teams import TeamCatalogue, TeamRecord
+
+__all__ = [
+    "AmbiguousLookupError",
+    "CatalogueError",
+    "DashboardBrowsePage",
+    "DashboardCatalogue",
+    "DashboardFolderCatalogue",
+    "DashboardFolderRecord",
+    "DashboardRecord",
+    "DataSourceCatalogue",
+    "DataSourceRecord",
+    "DatasetCatalogue",
+    "DatasetRecord",
+    "FigureCatalogue",
+    "FigureRecord",
+    "GlobalSearch",
+    "KpiCatalogue",
+    "KpiRecord",
+    "NotFoundError",
+    "Page",
+    "SearchGroup",
+    "SearchItem",
+    "TeamCatalogue",
+    "TeamRecord",
+]

northstar_sdk/catalogue/base.py

@@ -0,0 +1,200 @@
+"""Base catalogue client helpers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, Unpack
+
+from northstar_sdk.catalogue.exceptions import AmbiguousLookupError, NotFoundError
+from northstar_sdk.catalogue.page import Page, iter_all_pages
+from northstar_sdk.types.responses import CatalogueListExtraParams
+from northstar_sdk.types.json import JsonObject
+
+if TYPE_CHECKING:
+    from northstar_sdk.client import Client
+
+class RecordBase:
+    """Common fields for catalogue read models."""
+
+    id: str
+    raw: dict[str, Any]
+
+    def __init__(self, raw: dict[str, Any], *, id_key: str = "id") -> None:
+        self.raw = raw
+        resolved = raw.get(id_key)
+        if not resolved or not isinstance(resolved, str):
+            raise ValueError(f"Catalogue record missing string {id_key!r}")
+        self.id = resolved
+
+
+TRecord = TypeVar("TRecord", bound=RecordBase)
+
+class NamedCatalogue(ABC, Generic[TRecord]):
+    """
+    List/get/find helpers for a named catalogue resource.
+
+    Subclasses implement :meth:`_parse_record` and :meth:`_fetch_list_page`.
+    """
+
+    name_field: str = "name"
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    @abstractmethod
+    def _parse_record(self, raw: dict[str, Any]) -> TRecord:
+        ...
+
+    @abstractmethod
+    def _fetch_list_page(
+        self,
+        *,
+        page: int,
+        limit: int,
+        search: str | None,
+        **params: Any,
+    ) -> Page[TRecord]:
+        ...
+
+    @abstractmethod
+    def _get_raw(self, resource_id: str) -> dict[str, Any] | None:
+        ...
+
+    def list(
+        self,
+        *,
+        search: str | None = None,
+        page: int = 1,
+        limit: int = 20,
+        **params: Unpack[CatalogueListExtraParams],
+    ) -> Page[TRecord]:
+        """List resources visible to this API key (partial name search when ``search`` is set)."""
+        if page < 1:
+            raise ValueError("page must be >= 1")
+        if limit < 1:
+            raise ValueError("limit must be >= 1")
+        return self._fetch_list_page(
+            page=page,
+            limit=limit,
+            search=search,
+            **params,
+        )
+
+    def list_all(
+        self,
+        *,
+        search: str | None = None,
+        limit: int = 100,
+        **params: Unpack[CatalogueListExtraParams],
+    ) -> list[TRecord]:
+        """Fetch all pages and return a flat list."""
+
+        def fetch(p: int) -> Page[TRecord]:
+            return self.list(search=search, page=p, limit=limit, **params)
+
+        return list(iter_all_pages(fetch))
+
+    def get(self, resource_id: str) -> TRecord | None:
+        """Return one resource by id, or ``None`` if missing or forbidden."""
+        raw = self._get_raw(resource_id)
+        if raw is None:
+            return None
+        return self._parse_record(raw)
+
+    def find_by_id(self, resource_id: str) -> TRecord | None:
+        """Alias for :meth:`get`."""
+        return self.get(resource_id)
+
+    def get_or_raise(self, resource_id: str) -> TRecord:
+        record = self.get(resource_id)
+        if record is None:
+            raise NotFoundError(f"No accessible resource with id {resource_id!r}")
+        return record
+
+    def find_by_name(
+        self,
+        name: str,
+        *,
+        exact: bool = True,
+        limit: int = 100,
+        **list_params: Unpack[CatalogueListExtraParams],
+    ) -> TRecord:
+        """
+        Resolve a resource by display name.
+
+        Uses list ``search`` then filters client-side. Raises
+        :class:`NotFoundError` when none match; :class:`AmbiguousLookupError`
+        when more than one exact match exists.
+        """
+        needle = name.strip()
+        if not needle:
+            raise ValueError("name must be non-empty")
+
+        matches: list[TRecord] = []
+        page_num = 1
+        while True:
+            page = self.list(
+                search=needle, page=page_num, limit=limit, **list_params
+            )
+            for item in page.items:
+                label = _record_label(item, self.name_field)
+                if exact:
+                    if label.casefold() == needle.casefold():
+                        matches.append(item)
+                else:
+                    if needle.casefold() in label.casefold():
+                        matches.append(item)
+            if not page.has_next:
+                break
+            page_num += 1
+
+        if not matches:
+            raise NotFoundError(
+                f"No accessible resource with name {name!r} (exact={exact})"
+            )
+        if len(matches) > 1:
+            ids = ", ".join(m.id for m in matches[:5])
+            suffix = "…" if len(matches) > 5 else ""
+            raise AmbiguousLookupError(
+                f"Multiple resources named {name!r}: {ids}{suffix}"
+            )
+        return matches[0]
+
+
+def _record_label(record: Any, name_field: str) -> str:
+    if hasattr(record, name_field):
+        value = getattr(record, name_field)
+        if isinstance(value, str):
+            return value
+    raw = getattr(record, "raw", None)
+    if isinstance(raw, dict):
+        candidate = raw.get(name_field)
+        if isinstance(candidate, str):
+            return candidate
+    return ""
+
+
+def as_dict(value: Any) -> dict[str, Any]:
+    """Narrow an optional JSON object to ``dict`` for type checkers."""
+    return value if isinstance(value, dict) else {}
+
+
+def as_int(value: Any, default: int = 0) -> int:
+    """Coerce JSON pagination counters to ``int``."""
+    if isinstance(value, bool):
+        return default
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, str):
+        try:
+            return int(value)
+        except ValueError:
+            return default
+    return default
+
+
+def build_params(**kwargs: Any) -> dict[str, Any]:
+    """Drop ``None`` values for query strings."""
+    return {k: v for k, v in kwargs.items() if v is not None}

northstar_sdk/catalogue/dashboard_folders.py

@@ -0,0 +1,116 @@
+"""Dashboard folder catalogue queries."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from northstar_sdk.catalogue.dashboards import DashboardBrowsePage, DashboardFolderRecord
+from northstar_sdk.catalogue.exceptions import AmbiguousLookupError, NotFoundError
+from northstar_sdk.catalogue.page import Page
+
+if TYPE_CHECKING:
+    from northstar_sdk.client import Client
+
+
+class DashboardFolderCatalogue:
+    """
+    Browse and resolve dashboard folders visible to the API key user.
+
+    There is no flat list or single-folder GET API; use :meth:`browse` per
+    folder level, or :meth:`get` / :meth:`find_by_id` to walk the catalogue tree.
+    """
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def browse(
+        self,
+        *,
+        folder_chain: list[str] | None = None,
+    ) -> DashboardBrowsePage:
+        """List subfolders and dashboards at one catalogue level."""
+        from northstar_sdk.catalogue.dashboards import DashboardCatalogue
+
+        return DashboardCatalogue(self._client).browse(folder_chain=folder_chain)
+
+    def list(
+        self,
+        *,
+        folder_chain: list[str] | None = None,
+    ) -> Page[DashboardFolderRecord]:
+        """Subfolders at the given catalogue level (not including nested descendants)."""
+        browse = self.browse(folder_chain=folder_chain)
+        items = browse.folders
+        total = len(items)
+        return Page(items, 1, max(total, 1), total, 1 if total else 0)
+
+    def get(self, folder_id: str) -> DashboardFolderRecord | None:
+        """Return one folder by id, or ``None`` if missing or not visible."""
+        return self._find_in_tree(folder_id)
+
+    def find_by_id(self, folder_id: str) -> DashboardFolderRecord | None:
+        """Alias for :meth:`get`."""
+        return self.get(folder_id)
+
+    def get_or_raise(self, folder_id: str) -> DashboardFolderRecord:
+        record = self.get(folder_id)
+        if record is None:
+            raise NotFoundError(
+                f"No accessible dashboard folder with id {folder_id!r}"
+            )
+        return record
+
+    def find_by_name(
+        self,
+        name: str,
+        *,
+        folder_chain: list[str] | None = None,
+        exact: bool = True,
+    ) -> DashboardFolderRecord:
+        """
+        Resolve a folder by display name at one catalogue level.
+
+        ``folder_chain`` is the path from the root to the parent folder (empty =
+        root). Raises :class:`NotFoundError` when none match;
+        :class:`AmbiguousLookupError` when more than one exact match exists.
+        """
+        needle = name.strip()
+        if not needle:
+            raise ValueError("name must be non-empty")
+
+        browse = self.browse(folder_chain=folder_chain)
+        matches: list[DashboardFolderRecord] = []
+        for folder in browse.folders:
+            if exact:
+                if folder.name.casefold() == needle.casefold():
+                    matches.append(folder)
+            elif needle.casefold() in folder.name.casefold():
+                matches.append(folder)
+
+        if not matches:
+            raise NotFoundError(
+                f"No accessible dashboard folder named {name!r} at this level"
+            )
+        if len(matches) > 1:
+            ids = ", ".join(m.id for m in matches[:5])
+            suffix = "…" if len(matches) > 5 else ""
+            raise AmbiguousLookupError(
+                f"Multiple dashboard folders named {name!r}: {ids}{suffix}"
+            )
+        return matches[0]
+
+    def _find_in_tree(
+        self,
+        folder_id: str,
+        folder_chain: list[str] | None = None,
+    ) -> DashboardFolderRecord | None:
+        browse = self.browse(folder_chain=folder_chain)
+        for folder in browse.folders:
+            if folder.id == folder_id:
+                return folder
+            found = self._find_in_tree(
+                folder_id, (folder_chain or []) + [folder.id]
+            )
+            if found is not None:
+                return found
+        return None

northstar_sdk/catalogue/dashboards.py

@@ -0,0 +1,187 @@
+"""Dashboard catalogue queries (browse by folder)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from northstar_sdk.catalogue.base import RecordBase, build_params
+from northstar_sdk.catalogue.page import Page
+from northstar_sdk.types.responses import DashboardBreadcrumbItem
+
+if TYPE_CHECKING:
+    from northstar_sdk.client import Client
+
+
+@dataclass
+class DashboardFolderRecord(RecordBase):
+    name: str
+    color: str | None
+    description: str | None
+    parent_folder_id: str | None
+    dashboard_count: int
+
+    def __init__(self, raw: dict[str, Any]) -> None:
+        super().__init__(raw)
+        self.name = str(raw.get("name") or "")
+        color = raw.get("color")
+        self.color = color if isinstance(color, str) else None
+        desc = raw.get("description")
+        self.description = desc if isinstance(desc, str) else None
+        parent = raw.get("parentFolderId")
+        self.parent_folder_id = parent if isinstance(parent, str) else None
+        self.dashboard_count = int(raw.get("dashboardCount") or 0)
+
+
+@dataclass
+class DashboardRecord(RecordBase):
+    title: str
+    description: str | None
+    folder_id: str | None
+    embed_url: str | None
+
+    def __init__(self, raw: dict[str, Any]) -> None:
+        super().__init__(raw)
+        self.title = str(raw.get("title") or "")
+        desc = raw.get("description")
+        self.description = desc if isinstance(desc, str) else None
+        folder = raw.get("folderId")
+        self.folder_id = folder if isinstance(folder, str) else None
+        url = raw.get("embedUrl")
+        self.embed_url = url if isinstance(url, str) else None
+
+
+@dataclass
+class DashboardBrowsePage:
+    """One folder level in the dashboard catalogue."""
+
+    current_folder_id: str | None
+    folders: list[DashboardFolderRecord]
+    dashboards: list[DashboardRecord]
+    breadcrumbs: list[DashboardBreadcrumbItem]
+
+    @property
+    def items(self) -> list[DashboardRecord | DashboardFolderRecord]:
+        return [*self.folders, *self.dashboards]
+
+
+class DashboardCatalogue:
+    """
+    Browse dashboards and folders visible to the API key user.
+
+    There is no flat searchable list API; use :meth:`browse` per folder level
+    or :class:`~northstar_sdk.catalogue.search.GlobalSearch` for cross-folder title search.
+    """
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def browse(
+        self,
+        *,
+        folder_chain: list[str] | None = None,
+    ) -> DashboardBrowsePage:
+        """
+        List folders and dashboards at one catalogue level.
+
+        ``folder_chain`` is the ordered list of folder UUIDs from the catalogue
+        root (empty = root).
+        """
+        chain = folder_chain or []
+        params = build_params(
+            chain=",".join(chain) if chain else None,
+        )
+        result = self._client.get("/feature/dashboards/browse", params=params)
+        if not isinstance(result, dict):
+            return DashboardBrowsePage(None, [], [], [])
+        data = result.get("data")
+        if not isinstance(data, dict):
+            return DashboardBrowsePage(None, [], [], [])
+        folders_raw = data.get("folders")
+        dashboards_raw = data.get("dashboards")
+        breadcrumbs = data.get("breadcrumbs")
+        folders = [
+            DashboardFolderRecord(row)
+            for row in (folders_raw if isinstance(folders_raw, list) else [])
+            if isinstance(row, dict)
+        ]
+        dashboards = [
+            DashboardRecord(row)
+            for row in (dashboards_raw if isinstance(dashboards_raw, list) else [])
+            if isinstance(row, dict)
+        ]
+        current = data.get("currentFolderId")
+        current_id = current if isinstance(current, str) else None
+        crumbs: list[DashboardBreadcrumbItem] = []
+        if isinstance(breadcrumbs, list):
+            for item in breadcrumbs:
+                if isinstance(item, dict):
+                    crumbs.append(item)  # type: ignore[arg-type]
+        return DashboardBrowsePage(current_id, folders, dashboards, crumbs)
+
+    def list(
+        self,
+        *,
+        folder_chain: list[str] | None = None,
+    ) -> Page[DashboardRecord]:
+        """Dashboards at the given folder level (not including subfolders)."""
+        browse = self.browse(folder_chain=folder_chain)
+        items = browse.dashboards
+        total = len(items)
+        return Page(items, 1, max(total, 1), total, 1 if total else 0)
+
+    def get(self, dashboard_id: str) -> DashboardRecord | None:
+        result = self._client.get_optional(f"/feature/dashboards/{dashboard_id}")
+        if not isinstance(result, dict):
+            return None
+        dashboard = result.get("dashboard")
+        if isinstance(dashboard, dict):
+            return DashboardRecord(dashboard)
+        data = result.get("data")
+        if isinstance(data, dict):
+            return DashboardRecord(data)
+        return None
+
+    def find_by_id(self, dashboard_id: str) -> DashboardRecord | None:
+        return self.get(dashboard_id)
+
+    def find_by_title(
+        self,
+        title: str,
+        *,
+        exact: bool = True,
+    ) -> DashboardRecord:
+        """Search dashboards by title via global search (min 2 characters)."""
+        from northstar_sdk.catalogue.exceptions import AmbiguousLookupError, NotFoundError
+        from northstar_sdk.catalogue.search import GlobalSearch
+
+        if len(title.strip()) < 2:
+            raise ValueError(
+                "title must be at least 2 characters for catalogue search"
+            )
+        search = GlobalSearch(self._client)
+        groups = search.query(title)
+        matches: list[DashboardRecord] = []
+        for group in groups:
+            for item in group.items:
+                if item.type != "dashboard":
+                    continue
+                label = item.label
+                if exact:
+                    if label.casefold() == title.strip().casefold():
+                        matches.append(
+                            DashboardRecord({"id": item.id, "title": label})
+                        )
+                elif title.strip().casefold() in label.casefold():
+                    matches.append(
+                        DashboardRecord({"id": item.id, "title": label})
+                    )
+        if not matches:
+            raise NotFoundError(f"No accessible dashboard with title {title!r}")
+        if len(matches) > 1:
+            raise AmbiguousLookupError(
+                f"Multiple dashboards titled {title!r}: "
+                + ", ".join(m.id for m in matches[:5])
+            )
+        full = self.get(matches[0].id)
+        return full if full is not None else matches[0]

northstar_sdk/catalogue/data_sources.py

@@ -0,0 +1,75 @@
+"""Data source catalogue queries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from northstar_sdk.catalogue.base import NamedCatalogue, RecordBase, build_params
+from northstar_sdk.catalogue.page import Page
+
+
+@dataclass
+class DataSourceRecord(RecordBase):
+    name: str
+    slug: str | None
+    description: str | None
+
+    def __init__(self, raw: dict[str, Any]) -> None:
+        super().__init__(raw)
+        self.name = str(raw.get("name") or "")
+        slug = raw.get("slug")
+        self.slug = slug if isinstance(slug, str) else None
+        desc = raw.get("description")
+        self.description = desc if isinstance(desc, str) else None
+
+
+class DataSourceCatalogue(NamedCatalogue[DataSourceRecord]):
+    """Query data sources visible to the API key user."""
+
+    name_field = "name"
+
+    def _parse_record(self, raw: dict[str, Any]) -> DataSourceRecord:
+        return DataSourceRecord(raw)
+
+    def _get_raw(self, resource_id: str) -> dict[str, Any] | None:
+        result = self._client.get_optional(f"/feature/data-sources/{resource_id}")
+        if isinstance(result, dict):
+            nested = result.get("dataSource")
+            if isinstance(nested, dict):
+                return nested
+            return result
+        return None
+
+    def _fetch_list_page(
+        self,
+        *,
+        page: int,
+        limit: int,
+        search: str | None,
+        **params: Any,
+    ) -> Page[DataSourceRecord]:
+        del page, limit  # API returns full list
+        query = build_params(
+            search=search or None,
+            categoryId=params.pop("category_id", None),
+            **params,
+        )
+        result = self._client.get("/feature/data-sources", params=query)
+        if not isinstance(result, dict):
+            return Page([], 1, 0, 0, 0)
+        rows = result.get("dataSources")
+        items = [
+            self._parse_record(row)
+            for row in (rows if isinstance(rows, list) else [])
+            if isinstance(row, dict)
+        ]
+        total = len(items)
+        return Page(items, 1, total, total, 1 if total else 0)
+
+    def find_by_slug(self, slug: str) -> DataSourceRecord | None:
+        needle = slug.strip().casefold()
+        for item in self.list_all():
+            if item.slug and item.slug.casefold() == needle:
+                return item
+        return None