datacosmos 0.0.17__tar.gz → 0.0.27__tar.gz

{datacosmos-0.0.17 → datacosmos-0.0.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datacosmos
-Version: 0.0.17
+Version: 0.0.27
 Summary: A library for interacting with DataCosmos from Python code
 Author-email: Open Cosmos <support@open-cosmos.com>
 Classifier: Programming Language :: Python :: 3
@@ -16,6 +16,7 @@ Requires-Dist: pystac==1.12.1
 Requires-Dist: pyyaml==6.0.2
 Requires-Dist: structlog==24.4.0
 Requires-Dist: tenacity>=8.2.3
+Requires-Dist: shapely>=1.8.0
 Provides-Extra: dev
 Requires-Dist: black==22.3.0; extra == "dev"
 Requires-Dist: ruff==0.9.5; extra == "dev"

{datacosmos-0.0.17 → datacosmos-0.0.27}/datacosmos/auth/local_authenticator.py

@@ -7,7 +7,7 @@ import requests
 
 from datacosmos.auth.base_authenticator import AuthResult, BaseAuthenticator
 from datacosmos.auth.local_token_fetcher import LocalTokenFetcher
-from datacosmos.exceptions.datacosmos_exception import DatacosmosException
+from datacosmos.exceptions import AuthenticationError
 
 
 class LocalAuthenticator(BaseAuthenticator):
@@ -36,7 +36,7 @@ class LocalAuthenticator(BaseAuthenticator):
                 token_file=Path(auth.cache_file).expanduser(),
             )
         except Exception as e:
-            raise DatacosmosException(
+            raise AuthenticationError(
                 f"Failed to initialize LocalTokenFetcher: {e}"
             ) from e
 
@@ -52,7 +52,7 @@ class LocalAuthenticator(BaseAuthenticator):
                 http_client=http_client, token=token, token_expiry=token_expiry
             )
         except Exception as e:
-            raise DatacosmosException(f"Local authentication failed: {e}") from e
+            raise AuthenticationError(f"Local authentication failed: {e}") from e
 
     def refresh_token(self) -> AuthResult:
         """Refreshes the local token non-interactively."""
@@ -69,4 +69,4 @@ class LocalAuthenticator(BaseAuthenticator):
                 http_client=http_client, token=token, token_expiry=token_expiry
             )
         except Exception as e:
-            raise DatacosmosException(f"Local token refresh failed: {e}") from e
+            raise AuthenticationError(f"Local token refresh failed: {e}") from e

{datacosmos-0.0.17 → datacosmos-0.0.27}/datacosmos/auth/m2m_authenticator.py

@@ -3,7 +3,9 @@ from datetime import datetime, timedelta, timezone
 
 import requests
 from oauthlib.oauth2 import BackendApplicationClient
-from requests.exceptions import ConnectionError, HTTPError, RequestException, Timeout
+from requests.exceptions import ConnectionError
+from requests.exceptions import HTTPError as RequestsHTTPError
+from requests.exceptions import RequestException, Timeout
 from requests_oauthlib import OAuth2Session
 from tenacity import (
     retry,
@@ -13,7 +15,7 @@ from tenacity import (
 )
 
 from datacosmos.auth.base_authenticator import AuthResult, BaseAuthenticator
-from datacosmos.exceptions.datacosmos_exception import DatacosmosException
+from datacosmos.exceptions import AuthenticationError
 
 
 class M2MAuthenticator(BaseAuthenticator):
@@ -51,10 +53,10 @@ class M2MAuthenticator(BaseAuthenticator):
             return AuthResult(
                 http_client=http_client, token=token, token_expiry=token_expiry
             )
-        except (HTTPError, ConnectionError, Timeout) as e:
-            raise DatacosmosException(f"M2M authentication failed: {e}") from e
+        except (RequestsHTTPError, ConnectionError, Timeout) as e:
+            raise AuthenticationError(f"M2M authentication failed: {e}") from e
         except RequestException as e:
-            raise DatacosmosException(
+            raise AuthenticationError(
                 f"Unexpected request failure during M2M authentication: {e}"
             ) from e
 

{datacosmos-0.0.17 → datacosmos-0.0.27}/datacosmos/config/auth/factory.py

@@ -5,11 +5,6 @@ This module normalizes the `authentication` config into a concrete model:
 - `apply_auth_defaults` fills sensible defaults per auth type without inventing secrets.
 - `check_required_auth_fields` enforces the minimum required inputs.
 - `normalize_authentication` runs the whole pipeline.
-
-Design notes:
-- Auth models accept partial data (fields are Optional with None defaults).
-- We DO NOT pass `None` explicitly when constructing models here.
-- Required-ness is enforced centrally by `check_required_auth_fields`, not by model init.
 """
 
 from typing import Optional, Union, cast
@@ -28,54 +23,51 @@ from datacosmos.config.models.local_user_account_authentication_config import (
     LocalUserAccountAuthenticationConfig,
 )
 from datacosmos.config.models.m2m_authentication_config import M2MAuthenticationConfig
+from datacosmos.exceptions import AuthenticationError
 
 AuthModel = Union[M2MAuthenticationConfig, LocalUserAccountAuthenticationConfig]
 
 
 def parse_auth_config(raw: dict | AuthModel | None) -> Optional[AuthModel]:
-    """Turn a raw dict (e.g., from YAML) into a concrete auth model.
-
-    - If `raw` is already an auth model (M2M or local), return it unchanged.
-    - If `raw` is a dict, choose/validate the type using `raw['type']`
-      (or DEFAULT_AUTH_TYPE), then construct the corresponding model.
-      For missing fields we *may* apply non-secret defaults (endpoints, etc.).
-    """
-    if raw is None or isinstance(
-        raw, (M2MAuthenticationConfig, LocalUserAccountAuthenticationConfig)
-    ):
+    """Turn a raw dict (e.g., from YAML/env) into a concrete auth model."""
+    if isinstance(raw, (M2MAuthenticationConfig, LocalUserAccountAuthenticationConfig)):
         return cast(Optional[AuthModel], raw)
 
-    auth_type = _normalize_auth_type(raw.get("type") or DEFAULT_AUTH_TYPE)
+    if raw is None:
+        raw_data = {}
+    else:
+        raw_data = raw.copy()
+
+    if raw is None and not raw_data:
+        return None
+
+    auth_type = _normalize_auth_type(raw_data.get("type") or DEFAULT_AUTH_TYPE)
 
     if auth_type == "local":
         return LocalUserAccountAuthenticationConfig(
             type="local",
-            client_id=raw.get("client_id"),
-            authorization_endpoint=raw.get(
+            client_id=raw_data.get("client_id"),
+            authorization_endpoint=raw_data.get(
                 "authorization_endpoint", DEFAULT_LOCAL_AUTHORIZATION_ENDPOINT
             ),
-            token_endpoint=raw.get("token_endpoint", DEFAULT_LOCAL_TOKEN_ENDPOINT),
-            redirect_port=raw.get("redirect_port", DEFAULT_LOCAL_REDIRECT_PORT),
-            scopes=raw.get("scopes", DEFAULT_LOCAL_SCOPES),
-            audience=raw.get("audience", DEFAULT_AUTH_AUDIENCE),
-            cache_file=raw.get("cache_file", DEFAULT_LOCAL_CACHE_FILE),
+            token_endpoint=raw_data.get("token_endpoint", DEFAULT_LOCAL_TOKEN_ENDPOINT),
+            redirect_port=raw_data.get("redirect_port", DEFAULT_LOCAL_REDIRECT_PORT),
+            scopes=raw_data.get("scopes", DEFAULT_LOCAL_SCOPES),
+            audience=raw_data.get("audience", DEFAULT_AUTH_AUDIENCE),
+            cache_file=raw_data.get("cache_file", DEFAULT_LOCAL_CACHE_FILE),
         )
 
     return M2MAuthenticationConfig(
         type="m2m",
-        token_url=raw.get("token_url", DEFAULT_AUTH_TOKEN_URL),
-        audience=raw.get("audience", DEFAULT_AUTH_AUDIENCE),
-        client_id=raw.get("client_id"),
-        client_secret=raw.get("client_secret"),
+        token_url=raw_data.get("token_url", DEFAULT_AUTH_TOKEN_URL),
+        audience=raw_data.get("audience", DEFAULT_AUTH_AUDIENCE),
+        client_id=raw_data.get("client_id"),
+        client_secret=raw_data.get("client_secret"),
     )
 
 
 def apply_auth_defaults(auth: AuthModel | None) -> AuthModel:
-    """Fill in any missing defaults by type (non-secret values only).
-
-    If `auth` is None, construct a default "shell" based on DEFAULT_AUTH_TYPE,
-    without passing None for unknown credentials.
-    """
+    """Fill in any missing defaults by type (non-secret values only)."""
     if auth is None:
         default_type = _normalize_auth_type(DEFAULT_AUTH_TYPE)
         if default_type == "local":
@@ -101,7 +93,6 @@ def apply_auth_defaults(auth: AuthModel | None) -> AuthModel:
         auth.audience = auth.audience or DEFAULT_AUTH_AUDIENCE
         return auth
 
-    # Local defaults (Pydantic already coerces types; only set when missing)
     auth.type = auth.type or "local"
     auth.authorization_endpoint = (
         auth.authorization_endpoint or DEFAULT_LOCAL_AUTHORIZATION_ENDPOINT
@@ -116,22 +107,18 @@ def apply_auth_defaults(auth: AuthModel | None) -> AuthModel:
 
 
 def check_required_auth_fields(auth: AuthModel) -> None:
-    """Enforce required fields per auth type.
-
-    - m2m requires client_id and client_secret.
-    - local requires client_id.
-    """
+    """Enforce required fields per auth type."""
     if isinstance(auth, M2MAuthenticationConfig):
         missing = [f for f in ("client_id", "client_secret") if not getattr(auth, f)]
         if missing:
-            raise ValueError(
+            raise AuthenticationError(
                 f"Missing required authentication fields for m2m: {', '.join(missing)}"
             )
         return
 
     if isinstance(auth, LocalUserAccountAuthenticationConfig):
         if not auth.client_id:
-            raise ValueError(
+            raise AuthenticationError(
                 "Missing required authentication field for local: client_id"
             )
         return

{datacosmos-0.0.17 → datacosmos-0.0.27}/datacosmos/config/config.py

@@ -7,7 +7,7 @@ and supports environment variable-based overrides.
 
 from typing import Optional
 
-from pydantic import field_validator
+from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from datacosmos.config.auth.factory import normalize_authentication, parse_auth_config
@@ -18,6 +18,10 @@ from datacosmos.config.constants import (
 )
 from datacosmos.config.loaders.yaml_source import yaml_settings_source
 from datacosmos.config.models.authentication_config import AuthenticationConfig
+from datacosmos.config.models.local_user_account_authentication_config import (
+    LocalUserAccountAuthenticationConfig,
+)
+from datacosmos.config.models.m2m_authentication_config import M2MAuthenticationConfig
 from datacosmos.config.models.url import URL
 
 
@@ -31,9 +35,14 @@ class Config(BaseSettings):
     )
 
     authentication: Optional[AuthenticationConfig] = None
-    stac: URL | None = None
-    datacosmos_cloud_storage: URL | None = None
-    datacosmos_public_cloud_storage: URL | None = None
+
+    stac: URL = Field(default_factory=lambda: URL(**DEFAULT_STAC))
+    datacosmos_cloud_storage: URL = Field(
+        default_factory=lambda: URL(**DEFAULT_STORAGE)
+    )
+    datacosmos_public_cloud_storage: URL = Field(
+        default_factory=lambda: URL(**DEFAULT_STORAGE)
+    )
 
     @classmethod
     def settings_customise_sources(cls, *args, **kwargs):
@@ -65,13 +74,6 @@ class Config(BaseSettings):
     def _parse_authentication(cls, raw):
         if raw is None:
             return None
-        from datacosmos.config.models.local_user_account_authentication_config import (
-            LocalUserAccountAuthenticationConfig,
-        )
-        from datacosmos.config.models.m2m_authentication_config import (
-            M2MAuthenticationConfig,
-        )
-
         if isinstance(
             raw, (M2MAuthenticationConfig, LocalUserAccountAuthenticationConfig)
         ):
@@ -84,18 +86,3 @@ class Config(BaseSettings):
     @classmethod
     def _validate_authentication(cls, auth: Optional[AuthenticationConfig]):
         return normalize_authentication(auth)
-
-    @field_validator("stac", mode="before")
-    @classmethod
-    def _default_stac(cls, value: URL | None) -> URL:
-        return value or URL(**DEFAULT_STAC)
-
-    @field_validator("datacosmos_cloud_storage", mode="before")
-    @classmethod
-    def _default_cloud_storage(cls, value: URL | None) -> URL:
-        return value or URL(**DEFAULT_STORAGE)
-
-    @field_validator("datacosmos_public_cloud_storage", mode="before")
-    @classmethod
-    def _default_public_cloud_storage(cls, value: URL | None) -> URL:
-        return value or URL(**DEFAULT_STORAGE)

{datacosmos-0.0.17 → datacosmos-0.0.27}/datacosmos/datacosmos_client.py

@@ -7,7 +7,9 @@ from datetime import datetime, timedelta, timezone
 from typing import Any, Callable, List, Optional
 
 import requests
-from requests.exceptions import ConnectionError, HTTPError, RequestException, Timeout
+from requests.exceptions import ConnectionError
+from requests.exceptions import HTTPError as RequestsHTTPError
+from requests.exceptions import RequestException, Timeout
 from requests_oauthlib import OAuth2Session
 from tenacity import (
     retry,
@@ -20,7 +22,7 @@ from datacosmos.auth.base_authenticator import BaseAuthenticator
 from datacosmos.auth.local_authenticator import LocalAuthenticator
 from datacosmos.auth.m2m_authenticator import M2MAuthenticator
 from datacosmos.config.config import Config
-from datacosmos.exceptions.datacosmos_exception import DatacosmosException
+from datacosmos.exceptions import AuthenticationError, DatacosmosError, HTTPError
 
 _log = logging.getLogger(__name__)
 
@@ -75,7 +77,7 @@ class DatacosmosClient:
         try:
             return Config.model_validate(cfg)
         except Exception as e:
-            raise DatacosmosException(
+            raise AuthenticationError(
                 "Invalid config provided to DatacosmosClient"
             ) from e
 
@@ -88,7 +90,7 @@ class DatacosmosClient:
         token_data = self._extract_token_data(http_session)
         self.token = token_data.get("access_token")
         if not self.token:
-            raise DatacosmosException(
+            raise AuthenticationError(
                 "Failed to extract access token from injected session"
             )
         self.token_expiry = self._compute_expiry(
@@ -103,11 +105,11 @@ class DatacosmosClient:
         if isinstance(http_session, requests.Session):
             auth_header = http_session.headers.get("Authorization", "")
             if not auth_header.startswith("Bearer "):
-                raise DatacosmosException(
+                raise AuthenticationError(
                     "Injected requests.Session must include a 'Bearer' token in its headers"
                 )
             return {"access_token": auth_header.split(" ", 1)[1]}
-        raise DatacosmosException(f"Unsupported session type: {type(http_session)}")
+        raise AuthenticationError(f"Unsupported session type: {type(http_session)}")
 
     def _compute_expiry(
         self,
@@ -134,7 +136,7 @@ class DatacosmosClient:
         elif auth_type == "local":
             self._authenticator = LocalAuthenticator(self.config)
         else:
-            raise DatacosmosException(f"Unsupported authentication type: {auth_type}")
+            raise AuthenticationError(f"Unsupported authentication type: {auth_type}")
 
         auth_result = self._authenticator.authenticate_and_build_session()
         self.token = auth_result.token
@@ -166,7 +168,7 @@ class DatacosmosClient:
                     {"Authorization": f"Bearer {self.token}"}
                 )
             else:
-                raise DatacosmosException(
+                raise AuthenticationError(
                     "Cannot refresh token, no authenticator initialized."
                 )
 
@@ -196,7 +198,7 @@ class DatacosmosClient:
             requests.Response: The HTTP response.
 
         Raises:
-            DatacosmosException: For any HTTP or request-related errors.
+            DatacosmosError: For any HTTP or request-related errors.
         """
         self._refresh_token_if_needed()
 
@@ -219,7 +221,7 @@ class DatacosmosClient:
                     _log.error("Response hook failed.", exc_info=True)
 
             return response
-        except HTTPError as e:
+        except RequestsHTTPError as e:
             status = getattr(e.response, "status_code", None)
             if status in (401, 403) and getattr(self, "_owns_session", False):
                 self._refresh_now()
@@ -227,17 +229,17 @@ class DatacosmosClient:
                 try:
                     retry_response.raise_for_status()
                     return retry_response
-                except HTTPError as e:
-                    raise DatacosmosException(
+                except RequestsHTTPError as e:
+                    raise HTTPError(
                         f"HTTP error during {method.upper()} request to {url} after refresh",
                         response=e.response,
                     ) from e
-            raise DatacosmosException(
+            raise HTTPError(
                 f"HTTP error during {method.upper()} request to {url}",
                 response=getattr(e, "response", None),
             ) from e
         except RequestException as e:
-            raise DatacosmosException(
+            raise DatacosmosError(
                 f"Unexpected request failure during {method.upper()} request to {url}: {e}"
             ) from e
 

datacosmos-0.0.27/datacosmos/exceptions/__init__.py

@@ -0,0 +1,15 @@
+"""Exceptions for the datacosmos package."""
+
+from .authentication_error import AuthenticationError
+from .datacosmos_error import DatacosmosError
+from .http_error import HTTPError
+from .stac_validation_error import StacValidationError
+from .upload_error import UploadError
+
+__all__ = [
+    "DatacosmosError",
+    "StacValidationError",
+    "AuthenticationError",
+    "HTTPError",
+    "UploadError",
+]

datacosmos-0.0.27/datacosmos/exceptions/authentication_error.py

@@ -0,0 +1,8 @@
+"""Exception raised for authentication failures."""
+from datacosmos.exceptions.datacosmos_error import DatacosmosError
+
+
+class AuthenticationError(DatacosmosError):
+    """Exception raised for authentication failures."""
+
+    pass

datacosmos-0.0.17/datacosmos/exceptions/datacosmos_exception.py → datacosmos-0.0.27/datacosmos/exceptions/datacosmos_error.py

@@ -6,11 +6,11 @@ from requests import Response
 from requests.exceptions import RequestException
 
 
-class DatacosmosException(RequestException):
+class DatacosmosError(RequestException):
     """Base exception class for all Datacosmos SDK exceptions."""
 
     def __init__(self, message: str, response: Optional[Response] = None):
-        """Initialize DatacosmosException.
+        """Initialize DatacosmosError.
 
         Args:
             message (str): The error message.

datacosmos-0.0.27/datacosmos/exceptions/http_error.py

@@ -0,0 +1,8 @@
+"""Exception raised for HTTP request failures."""
+from datacosmos.exceptions.datacosmos_error import DatacosmosError
+
+
+class HTTPError(DatacosmosError):
+    """Exception raised for HTTP request failures that wraps status codes."""
+
+    pass

datacosmos-0.0.27/datacosmos/exceptions/stac_validation_error.py

@@ -0,0 +1,8 @@
+"""Custom exception for STAC validation errors."""
+from datacosmos.exceptions.datacosmos_error import DatacosmosError
+
+
+class StacValidationError(DatacosmosError):
+    """Exception raised for errors in STAC item validation."""
+
+    pass

datacosmos-0.0.27/datacosmos/exceptions/upload_error.py

@@ -0,0 +1,23 @@
+"""Exception raised during asset upload operations."""
+from typing import Any, Optional
+
+from datacosmos.exceptions.datacosmos_error import DatacosmosError
+
+
+class UploadError(DatacosmosError):
+    """Exception raised during asset upload operations, including asset context."""
+
+    def __init__(self, message: str, asset_key: Optional[str] = None, **kwargs: Any):
+        """Initialize UploadError.
+
+        Args:
+            message (str): The error message.
+            asset_key (Optional[str]): The key of the asset that caused the failure.
+        """
+        self.asset_key = asset_key
+
+        # Modify message to include context if available
+        if asset_key:
+            message = f"[{asset_key}] {message}"
+
+        super().__init__(message, **kwargs)

{datacosmos-0.0.17 → datacosmos-0.0.27}/datacosmos/stac/collection/collection_client.py

@@ -6,7 +6,7 @@ from pystac import Collection, Extent, SpatialExtent, TemporalExtent
 from pystac.utils import str_to_datetime
 
 from datacosmos.datacosmos_client import DatacosmosClient
-from datacosmos.exceptions.datacosmos_exception import DatacosmosException
+from datacosmos.exceptions import HTTPError
 from datacosmos.stac.collection.models.collection_update import CollectionUpdate
 from datacosmos.utils.http_response.check_api_response import check_api_response
 
@@ -98,7 +98,10 @@ class CollectionClient:
         data = response.json()
 
         if isinstance(data, list):
-            return {"collections": data}
+            raise HTTPError(
+                f"Unexpected API response format during collection fetch. Expected dictionary, got list: {data}",
+                response=response,
+            )
 
         return data
 
@@ -147,7 +150,4 @@ class CollectionClient:
         try:
             return next_href.split("?")[1].split("=")[-1]
         except (IndexError, AttributeError) as e:
-            raise DatacosmosException(
-                f"Failed to parse pagination token from {next_href}",
-                response=e.response,
-            ) from e
+            raise HTTPError(f"Failed to parse pagination token from {next_href}") from e

datacosmos-0.0.27/datacosmos/stac/enums/processing_level.py

@@ -0,0 +1,28 @@
+"""Level enum class."""
+
+from enum import Enum
+
+
+class CaseInsensitiveEnum(Enum):
+    """An enum that can be initialized with case-insensitive strings."""
+
+    @classmethod
+    def _missing_(cls, value: object):
+        if isinstance(value, str):
+            for member in cls:
+                if member.value.lower() == value.lower():
+                    return member
+        return super()._missing_(value)
+
+
+class ProcessingLevel(CaseInsensitiveEnum):
+    """Enum class for the processing levels of the data."""
+
+    RAW = "RAW"
+    L0 = "l0"
+    L1A = "l1A"
+    L2A = "l2A"
+    L1B = "l1B"
+    L1C = "l1C"
+    L1D = "l1D"
+    L3 = "l3"

{datacosmos-0.0.17 → datacosmos-0.0.27}/datacosmos/stac/item/item_client.py

@@ -8,7 +8,7 @@ from typing import Generator, Optional
 from pystac import Item
 
 from datacosmos.datacosmos_client import DatacosmosClient
-from datacosmos.exceptions.datacosmos_exception import DatacosmosException
+from datacosmos.exceptions.datacosmos_error import DatacosmosError
 from datacosmos.stac.item.models.catalog_search_parameters import (
     CatalogSearchParameters,
 )
@@ -29,7 +29,7 @@ class ItemClient:
         self.client = client
         self.base_url = client.config.stac.as_domain_url()
 
-    def fetch_item(self, item_id: str, collection_id: str) -> Item:
+    def fetch_item(self, item_id: str, collection_id: str) -> DatacosmosItem:
         """Fetch a single STAC item by ID.
 
         Args:
@@ -37,12 +37,12 @@ class ItemClient:
             collection_id (str): The ID of the collection containing the item.
 
         Returns:
-            Item: The fetched STAC item.
+            DatacosmosItem: The fetched STAC item.
         """
         url = self.base_url.with_suffix(f"/collections/{collection_id}/items/{item_id}")
         response = self.client.get(url)
         check_api_response(response)
-        return Item.from_dict(response.json())
+        return DatacosmosItem.from_dict(response.json())
 
     def search_items(
         self, parameters: CatalogSearchParameters, project_id: str
@@ -74,15 +74,7 @@ class ItemClient:
             ValueError: If the item has no collection set.
             RequestError: If the API returns an error response.
         """
-        if isinstance(item, Item):
-            collection_id = item.collection_id or (
-                item.get_collection().id if item.get_collection() else None
-            )
-        else:
-            collection_id = item.collection
-
-        if not collection_id:
-            raise ValueError("Cannot create item: no collection_id found on item")
+        collection_id = self._get_collection_id(item, method="create")
 
         url = self.base_url.with_suffix(f"/collections/{collection_id}/items")
         item_json: dict = item.to_dict()
@@ -101,15 +93,10 @@ class ItemClient:
             ValueError: If the item has no collection set.
             RequestError: If the API returns an error response.
         """
-        if isinstance(item, Item):
-            collection_id = item.collection_id or (
-                item.get_collection().id if item.get_collection() else None
-            )
-        else:
-            collection_id = item.collection
+        collection_id = self._get_collection_id(item, method="add")
 
-        if not collection_id:
-            raise ValueError("Cannot create item: no collection_id found on item")
+        if not item.id:
+            raise ValueError("Cannot add item: no item_id found on item")
 
         url = self.base_url.with_suffix(f"/collections/{collection_id}/items/{item.id}")
         item_json: dict = item.to_dict()
@@ -150,24 +137,14 @@ class ItemClient:
             collection_id (str): The ID of the collection containing the item.
 
         Raises:
-            OCError: If the item is not found or deletion is forbidden.
+            DatacosmosError: If the item is not found or deletion is forbidden.
         """
         url = self.base_url.with_suffix(f"/collections/{collection_id}/items/{item_id}")
         response = self.client.delete(url)
         check_api_response(response)
 
     def _paginate_items(self, url: str, body: dict) -> Generator[Item, None, None]:
-        """Handle pagination for the STAC search POST endpoint.
-
-        Fetches items one page at a time using the 'next' link.
-
-        Args:
-            url (str): The base URL for the search endpoint.
-            body (dict): The request body containing search parameters.
-
-        Yields:
-            Item: Parsed STAC item.
-        """
+        """Handle pagination for the STAC search POST endpoint."""
         params = {"limit": body.get("limit", 10)}
 
         while True:
@@ -203,12 +180,39 @@ class ItemClient:
             Optional[str]: The extracted token, or None if parsing fails.
 
         Raises:
-            DatacosmosException: If pagination token extraction fails.
+            DatacosmosError: If pagination token extraction fails.
         """
         try:
             return next_href.split("?")[1].split("=")[-1]
         except (IndexError, AttributeError) as e:
-            raise DatacosmosException(
+            raise DatacosmosError(
                 f"Failed to parse pagination token from {next_href}",
                 response=e.response,
             ) from e
+
+    def _get_collection_id(self, item: Item | DatacosmosItem, method: str) -> str:
+        """Resolves the collection ID from an item.
+
+        Args:
+            item: The STAC item.
+            method: The client method calling this helper ("create" or "add").
+            is_strict: Check if strict validation is to be done.
+
+        Returns:
+            The collection_id.
+
+        Raises:
+            ValueError: If collection ID cannot be resolved.
+        """
+        if isinstance(item, Item):
+            collection_id = item.collection_id
+        else:
+            collection_id = item.collection
+
+        if not collection_id:
+            if method == "create":
+                raise ValueError("Cannot create item: no collection_id found on item")
+            else:
+                raise ValueError("Cannot add item: no collection_id found on item")
+
+        return collection_id