poelis-sdk 0.5.4__py3-none-any.whl

poelis_sdk/org_validation.py

@@ -0,0 +1,163 @@
+"""Organization validation utilities for the Poelis SDK.
+
+This module provides utilities for validating that data belongs to the
+configured organization, ensuring proper multi-tenant isolation.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .exceptions import ClientError
+
+
+class OrganizationValidationError(ClientError):
+    """Raised when data doesn't belong to the configured organization."""
+    
+    def __init__(self, message: str, expected_org_id: str, actual_org_id: Optional[str] = None) -> None:
+        """Initialize organization validation error.
+        
+        Args:
+            message: Error message describing the validation failure.
+            expected_org_id: The organization ID that was expected.
+            actual_org_id: The organization ID that was found (if any).
+        """
+        super().__init__(400, message)
+        self.expected_org_id = expected_org_id
+        self.actual_org_id = actual_org_id
+
+
+def validate_organization_id(data: Dict[str, Any], expected_org_id: str, data_type: str = "item") -> None:
+    """Validate that data belongs to the expected organization.
+    
+    Args:
+        data: The data dictionary to validate.
+        expected_org_id: The organization ID that should match.
+        data_type: Type of data being validated (for error messages).
+        
+    Raises:
+        OrganizationValidationError: If the data doesn't belong to the expected organization.
+    """
+    actual_org_id = data.get('orgId')
+    
+    if actual_org_id is None:
+        raise OrganizationValidationError(
+            f"{data_type.capitalize()} does not have an organization ID",
+            expected_org_id,
+            actual_org_id
+        )
+    
+    if actual_org_id != expected_org_id:
+        raise OrganizationValidationError(
+            f"{data_type.capitalize()} belongs to organization '{actual_org_id}', "
+            f"but client is configured for organization '{expected_org_id}'",
+            expected_org_id,
+            actual_org_id
+        )
+
+
+def filter_by_organization(data_list: List[Dict[str, Any]], expected_org_id: str, data_type: str = "items") -> List[Dict[str, Any]]:
+    """Filter a list of data to only include items from the expected organization.
+    
+    Args:
+        data_list: List of data dictionaries to filter.
+        expected_org_id: The organization ID to filter by.
+        data_type: Type of data being filtered (for logging).
+        
+    Returns:
+        Filtered list containing only data from the expected organization.
+    """
+    filtered = []
+    cross_org_count = 0
+    
+    for item in data_list:
+        item_org_id = item.get('orgId')
+        if item_org_id == expected_org_id:
+            filtered.append(item)
+        else:
+            cross_org_count += 1
+    
+    return filtered
+
+
+def validate_workspace_organization(workspace: Dict[str, Any], expected_org_id: str) -> None:
+    """Validate that a workspace belongs to the expected organization.
+    
+    Args:
+        workspace: The workspace dictionary to validate.
+        expected_org_id: The organization ID that should match.
+        
+    Raises:
+        OrganizationValidationError: If the workspace doesn't belong to the expected organization.
+    """
+    validate_organization_id(workspace, expected_org_id, "workspace")
+
+
+def validate_product_organization(product: Any, expected_org_id: str) -> None:
+    """Validate that a product belongs to the expected organization.
+    
+    Args:
+        product: The product object to validate (can be dict or Product model).
+        expected_org_id: The organization ID that should match.
+        
+    Raises:
+        OrganizationValidationError: If the product doesn't belong to the expected organization.
+    """
+    # Handle both dict and Product model
+    if hasattr(product, 'workspace_id'):
+        # Product model - we need to get the workspace to check its org
+        # This is a limitation of the current API design
+        pass  # We'll handle this in the client methods
+    elif isinstance(product, dict):
+        # Dict format - check if it has orgId directly
+        if 'orgId' in product:
+            validate_organization_id(product, expected_org_id, "product")
+        # If no orgId, we can't validate (backend should handle this)
+
+
+def validate_item_organization(item: Dict[str, Any], expected_org_id: str) -> None:
+    """Validate that an item belongs to the expected organization.
+    
+    Args:
+        item: The item dictionary to validate.
+        expected_org_id: The organization ID that should match.
+        
+    Raises:
+        OrganizationValidationError: If the item doesn't belong to the expected organization.
+    """
+    validate_organization_id(item, expected_org_id, "item")
+
+
+def get_organization_context_message(org_id: Optional[str]) -> str:
+    """Get a user-friendly message about the current organization context.
+    
+    The SDK now uses user-bound API keys. Organization and workspace access
+    are derived on the server from the authenticated user behind the key.
+    
+    Args:
+        org_id: Deprecated organization identifier (ignored).
+        
+    Returns:
+        A formatted message about the organization/key context.
+    """
+    if org_id:
+        # Kept for backwards compatibility if callers still pass an ID.
+        return f"🔒 Organization (derived from key): {org_id}"
+    return "🔒 SDK key is user-bound; org and workspaces are derived from the key on the server"
+
+
+def format_organization_error(error: OrganizationValidationError) -> str:
+    """Format an organization validation error for user display.
+    
+    Args:
+        error: The organization validation error.
+        
+    Returns:
+        A formatted error message.
+    """
+    return (
+        f"❌ Organization Mismatch: {error.message}\n"
+        f"   Expected: {error.expected_org_id}\n"
+        f"   Found: {error.actual_org_id or 'None'}\n"
+        f"   This usually means the data belongs to a different organization."
+    )

poelis_sdk/products.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generator, Optional
+
+from ._transport import Transport
+from .models import PaginatedProducts, PaginatedProductVersions, Product, ProductVersion
+
+if TYPE_CHECKING:
+    from .workspaces import WorkspacesClient
+
+"""Products resource client."""
+
+
+class ProductsClient:
+    """Client for product resources."""
+
+    def __init__(self, transport: Transport, workspaces_client: Optional["WorkspacesClient"] = None) -> None:
+        """Initialize with shared transport and optional workspaces client."""
+
+        self._t = transport
+        self._workspaces_client = workspaces_client
+
+    def list_by_workspace(self, *, workspace_id: str, q: Optional[str] = None, limit: int = 100, offset: int = 0) -> PaginatedProducts:
+        """List products using GraphQL for a given workspace.
+
+        Args:
+            workspace_id: Workspace ID to scope products.
+            q: Optional free-text filter.
+            limit: Page size.
+            offset: Offset for pagination.
+        """
+
+        query = (
+            "query($ws: ID!, $q: String, $limit: Int!, $offset: Int!) {\n"
+            "  products(workspaceId: $ws, q: $q, limit: $limit, offset: $offset) {\n"
+            "    id\n"
+            "    name\n"
+            "    readableId\n"
+            "    workspaceId\n"
+            "    baselineVersionNumber\n"
+            "  }\n"
+            "}"
+        )
+        variables = {"ws": workspace_id, "q": q, "limit": int(limit), "offset": int(offset)}
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+
+        products = payload.get("data", {}).get("products", [])
+
+        return PaginatedProducts(data=[Product(**r) for r in products], limit=limit, offset=offset)
+
+    def list_product_versions(self, *, product_id: str, limit: int = 50, offset: int = 0) -> PaginatedProductVersions:
+        """List versions for a given product.
+
+        Args:
+            product_id: Identifier of the product whose versions should be listed.
+            limit: Maximum number of versions to return (currently ignored by backend).
+            offset: Offset for pagination (currently ignored by backend).
+
+        Returns:
+            PaginatedProductVersions: Container with version data and pagination info.
+
+        Raises:
+            RuntimeError: If the GraphQL response contains errors.
+        """
+
+        query = (
+            "query($pid: ID!) {\n"
+            "  productVersions(productId: $pid) {\n"
+            "    productId\n"
+            "    versionNumber\n"
+            "    title\n"
+            "    description\n"
+            "    createdAt\n"
+            "  }\n"
+            "}"
+        )
+        variables = {"pid": product_id}
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+
+        versions = payload.get("data", {}).get("productVersions", [])
+
+        return PaginatedProductVersions(data=[ProductVersion(**v) for v in versions], limit=limit, offset=offset)
+
+    def set_product_baseline_version(self, *, product_id: str, version_number: int) -> Product:
+        """Set the baseline version for a product.
+
+        This wraps the ``setProductBaselineVersion`` GraphQL mutation and returns
+        the updated :class:`Product` including its ``baseline_version_number``.
+
+        Args:
+            product_id: Identifier of the product whose baseline should be updated.
+            version_number: Version number to mark as baseline.
+
+        Returns:
+            Product: The updated product with the new baseline version number.
+
+        Raises:
+            RuntimeError: If the GraphQL response contains errors.
+        """
+
+        query = (
+            "mutation SetBaseline($productId: ID!, $versionNumber: Int!) {\n"
+            "  setProductBaselineVersion(productId: $productId, versionNumber: $versionNumber) {\n"
+            "    id\n"
+            "    name\n"
+            "    readableId\n"
+            "    workspaceId\n"
+            "    baselineVersionNumber\n"
+            "  }\n"
+            "}"
+        )
+        variables = {"productId": product_id, "versionNumber": int(version_number)}
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+
+        product_data = payload.get("data", {}).get("setProductBaselineVersion")
+        if product_data is None:
+            raise RuntimeError("Malformed GraphQL response: missing 'setProductBaselineVersion' field")
+
+        return Product(**product_data)
+
+    def iter_all_by_workspace(self, *, workspace_id: str, q: Optional[str] = None, page_size: int = 100, start_offset: int = 0) -> Generator[Product, None, None]:
+        """Iterate products via GraphQL with offset pagination for a workspace."""
+
+        offset = start_offset
+        while True:
+            page = self.list_by_workspace(workspace_id=workspace_id, q=q, limit=page_size, offset=offset)
+            if not page.data:
+                break
+            for product in page.data:
+                yield product
+            offset += len(page.data)
+
+    def iter_all(self, *, q: Optional[str] = None, page_size: int = 100) -> Generator[Product, None, None]:
+        """Iterate products across all workspaces.
+        
+        Args:
+            q: Optional free-text filter.
+            page_size: Page size for each workspace iteration.
+            
+        Raises:
+            RuntimeError: If workspaces client is not available.
+        """
+        if self._workspaces_client is None:
+            raise RuntimeError("Workspaces client not available. Cannot iterate across all workspaces.")
+            
+        # Get all workspaces
+        workspaces = self._workspaces_client.list(limit=1000, offset=0)
+        
+        for workspace in workspaces:
+            workspace_id = workspace['id']
+            # Iterate through products in this workspace
+            for product in self.iter_all_by_workspace(workspace_id=workspace_id, q=q, page_size=page_size):
+                yield product
+
+

poelis_sdk/search.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ._transport import Transport
+
+"""Search resource client using GraphQL endpoints only."""
+
+
+class SearchClient:
+    """Client for /v1/search endpoints (products, items, properties)."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def products(self, *, q: str, workspace_id: str, limit: int = 20, offset: int = 0) -> Dict[str, Any]:
+        """Search/list products via GraphQL products(workspaceId, q)."""
+
+        query = (
+            "query($ws: ID!, $q: String, $limit: Int!, $offset: Int!) {\n"
+            "  products(workspaceId: $ws, q: $q, limit: $limit, offset: $offset) { id name workspaceId }\n"
+            "}"
+        )
+        variables = {"ws": workspace_id, "q": q, "limit": int(limit), "offset": int(offset)}
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        hits = payload.get("data", {}).get("products", [])
+        return {"query": q, "hits": hits, "total": None, "limit": limit, "offset": offset}
+
+    def items(self, *, q: Optional[str], product_id: str, parent_item_id: Optional[str] = None, limit: int = 20, offset: int = 0) -> Dict[str, Any]:
+        """Search/list items via GraphQL items(product_id, q, parent_item_id)."""
+
+        query = (
+            "query($pid: ID!, $q: String, $parent: ID, $limit: Int!, $offset: Int!) {\n"
+            "  items(productId: $pid, q: $q, parentItemId: $parent, limit: $limit, offset: $offset) { id name productId parentId owner position }\n"
+            "}"
+        )
+        variables = {"pid": product_id, "q": q, "parent": parent_item_id, "limit": int(limit), "offset": int(offset)}
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        hits = payload.get("data", {}).get("items", [])
+        return {"query": q, "hits": hits, "total": None, "limit": limit, "offset": offset}
+
+    def properties(self, *, q: str, workspace_id: Optional[str] = None, product_id: Optional[str] = None, item_id: Optional[str] = None, property_type: Optional[str] = None, category: Optional[str] = None, limit: int = 20, offset: int = 0, sort: Optional[str] = None) -> Dict[str, Any]:
+        """Search properties via GraphQL search_properties."""
+
+        query = (
+            "query($q: String!, $ws: ID, $pid: ID, $iid: ID, $ptype: String, $cat: String, $limit: Int!, $offset: Int!, $sort: String) {\n"
+            "  searchProperties(q: $q, workspaceId: $ws, productId: $pid, itemId: $iid, propertyType: $ptype, category: $cat, limit: $limit, offset: $offset, sort: $sort) {\n"
+            "    query total limit offset processingTimeMs\n"
+            "    hits { id workspaceId productId itemId propertyType name category value parsedValue owner }\n"
+            "  }\n"
+            "}"
+        )
+        variables: Dict[str, Any] = {
+            "q": q,
+            "ws": workspace_id,
+            "pid": product_id,
+            "iid": item_id,
+            "ptype": property_type,
+            "cat": category,
+            "limit": int(limit),
+            "offset": int(offset),
+            "sort": sort,
+        }
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        data = payload.get("data", {}).get("searchProperties", {})
+        # Normalize to match previous REST shape
+        return {
+            "query": data.get("query", q),
+            "hits": data.get("hits", []),
+            "total": data.get("total"),
+            "limit": data.get("limit", limit),
+            "offset": data.get("offset", offset),
+            "processing_time_ms": data.get("processingTimeMs", 0),
+        }
+
+

poelis_sdk/versions.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Generator, List, Optional
+
+from ._transport import Transport
+
+"""Versions resource client.
+
+Provides read-only access to product versions and their versioned items.
+This client is focused on versioned (snapshot) data; draft mutations should
+continue to go through the non-versioned clients.
+"""
+
+
+class VersionsClient:
+    """Client for product version resources."""
+
+    def __init__(self, transport: Transport) -> None:
+        """Initialize the client with shared transport.
+
+        Args:
+            transport: Shared HTTP/GraphQL transport used by the SDK.
+        """
+
+        self._t = transport
+
+    def list_items(
+        self,
+        *,
+        product_id: str,
+        version_number: int,
+        q: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """List versioned items for a specific product version via GraphQL.
+
+        This method returns the snapshot of items as they were frozen in the
+        specified product version. Draft items should be accessed through the
+        non-versioned `ItemsClient`.
+
+        Args:
+            product_id: Identifier of the parent product.
+            version_number: Version number of the product whose items to list.
+            q: Optional free-text filter applied to item name/description.
+            limit: Maximum number of items to return.
+            offset: Offset for pagination.
+
+        Returns:
+            List of item dictionaries belonging to the given product version.
+
+        Raises:
+            RuntimeError: If the GraphQL response contains errors.
+        """
+
+        query = (
+            "query($pid: ID!, $version: VersionInput!, $q: String, $limit: Int!, $offset: Int!) {\n"
+            "  items(productId: $pid, version: $version, q: $q, limit: $limit, offset: $offset) {\n"
+            "    id\n"
+            "    name\n"
+            "    readableId\n"
+            "    productId\n"
+            "    parentId\n"
+            "    owner\n"
+            "    position\n"
+            "  }\n"
+            "}"
+        )
+        variables = {
+            "pid": product_id,
+            "version": {"productId": product_id, "versionNumber": int(version_number)},
+            "q": q,
+            "limit": int(limit),
+            "offset": int(offset),
+        }
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+
+        items = payload.get("data", {}).get("items", [])
+
+        return items
+
+    def iter_items(
+        self,
+        *,
+        product_id: str,
+        version_number: int,
+        q: Optional[str] = None,
+        page_size: int = 100,
+        start_offset: int = 0,
+    ) -> Generator[Dict[str, Any], None, None]:
+        """Iterate versioned items for a specific product version.
+
+        Args:
+            product_id: Identifier of the parent product.
+            version_number: Version number whose items to iterate.
+            q: Optional free-text filter applied to item name/description.
+            page_size: Page size for each GraphQL request.
+            start_offset: Initial offset for pagination.
+
+        Yields:
+            Individual item dictionaries for the given product version.
+        """
+
+        offset = start_offset
+        while True:
+            page = self.list_items(
+                product_id=product_id,
+                version_number=version_number,
+                q=q,
+                limit=page_size,
+                offset=offset,
+            )
+            if not page:
+                break
+            for item in page:
+                yield item
+            offset += len(page)
+
+

poelis_sdk/workspaces.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ._transport import Transport
+
+"""Workspaces GraphQL client."""
+
+
+class WorkspacesClient:
+    """Client for querying workspaces via GraphQL."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list(self, *, limit: int = 50, offset: int = 0) -> List[Dict[str, Any]]:
+        """List workspaces (implicitly scoped by org via auth)."""
+
+        query = (
+            "query($limit: Int!, $offset: Int!) {\n"
+            "  workspaces(limit: $limit, offset: $offset) { id orgId name readableId }\n"
+            "}"
+        )
+        resp = self._t.graphql(query=query, variables={"limit": int(limit), "offset": int(offset)})
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        
+        workspaces = payload.get("data", {}).get("workspaces", [])
+        return workspaces
+
+    def get(self, *, workspace_id: str) -> Optional[Dict[str, Any]]:
+        """Get a single workspace by id via GraphQL."""
+
+        query = (
+            "query($id: ID!) {\n"
+            "  workspace(id: $id) { id orgId name readableId }\n"
+            "}"
+        )
+        resp = self._t.graphql(query=query, variables={"id": workspace_id})
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        
+        workspace = payload.get("data", {}).get("workspace")
+        return workspace
+
+