strapi-kit 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

strapi_kit/__init__.py

@@ -13,13 +13,13 @@ from .__version__ import __version__
 from .client import AsyncClient, SyncClient
 from .config_provider import (
     ConfigFactory,
-    ConfigurationError,
     create_config,
     load_config,
 )
 from .exceptions import (
     AuthenticationError,
     AuthorizationError,
+    ConfigurationError,
     ConflictError,
     FormatError,
     ImportExportError,

strapi_kit/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.2'
-__version_tuple__ = version_tuple = (0, 0, 2)
+__version__ = version = '0.0.3'
+__version_tuple__ = version_tuple = (0, 0, 3)
 
 __commit_id__ = commit_id = None

strapi_kit/client/async_client.py

@@ -8,7 +8,11 @@ import asyncio
 import logging
 from collections.abc import Callable
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..models.content_type import ComponentListItem, ContentTypeListItem
+    from ..models.content_type import ContentTypeSchema as CTBContentTypeSchema
 
 import httpx
 
@@ -1030,3 +1034,85 @@ class AsyncClient(BaseClient):
             succeeded=success_count,
             failed=len(failures),
         )
+
+    # Content-Type Builder API
+
+    async def get_content_types(
+        self,
+        *,
+        include_plugins: bool = False,
+    ) -> list["ContentTypeListItem"]:
+        """List all content types from Content-Type Builder API.
+
+        Retrieves schema information for all content types defined in Strapi.
+
+        Args:
+            include_plugins: Whether to include plugin content types
+                            (e.g., users-permissions). Defaults to False.
+
+        Returns:
+            List of ContentTypeListItem with uid, kind, info, and attributes
+
+        Examples:
+            >>> # Get only API content types
+            >>> content_types = await client.get_content_types()
+            >>> for ct in content_types:
+            ...     print(f"{ct.uid}: {ct.info.display_name}")
+            api::article.article: Article
+            api::category.category: Category
+
+            >>> # Include plugin content types
+            >>> all_types = await client.get_content_types(include_plugins=True)
+            >>> plugin_types = [ct for ct in all_types if ct.uid.startswith("plugin::")]
+        """
+
+        raw_response = await self.get("content-type-builder/content-types")
+        return self._parse_content_types_response(raw_response, include_plugins)
+
+    async def get_components(self) -> list["ComponentListItem"]:
+        """List all components from Content-Type Builder API.
+
+        Retrieves schema information for all components defined in Strapi.
+
+        Returns:
+            List of ComponentListItem with uid, category, info, and attributes
+
+        Examples:
+            >>> components = await client.get_components()
+            >>> for comp in components:
+            ...     print(f"{comp.category}/{comp.uid}: {comp.info.display_name}")
+            shared/shared.seo: SEO
+            blocks/blocks.hero: Hero Section
+        """
+
+        raw_response = await self.get("content-type-builder/components")
+        return self._parse_components_response(raw_response)
+
+    async def get_content_type_schema(self, uid: str) -> "CTBContentTypeSchema":
+        """Get full schema for a specific content type.
+
+        Retrieves detailed schema information including all field configurations.
+
+        Args:
+            uid: Content type UID (e.g., "api::article.article")
+
+        Returns:
+            CTBContentTypeSchema with complete field definitions
+
+        Raises:
+            NotFoundError: If content type doesn't exist
+
+        Examples:
+            >>> schema = await client.get_content_type_schema("api::article.article")
+            >>> schema.info.display_name
+            'Article'
+            >>> schema.attributes["title"]["type"]
+            'string'
+            >>> schema.is_relation_field("author")
+            True
+            >>> schema.get_relation_target("author")
+            'api::author.author'
+        """
+
+        raw_response = await self.get(f"content-type-builder/content-types/{uid}")
+        return self._parse_content_type_schema_response(raw_response)

strapi_kit/client/base.py

@@ -5,7 +5,11 @@ automatic response format detection, error handling, and authentication.
 """
 
 import logging
-from typing import Any, Literal
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from ..models.content_type import ComponentListItem, ContentTypeListItem
+    from ..models.content_type import ContentTypeSchema as CTBContentTypeSchema
 
 import httpx
 from tenacity import (
@@ -20,6 +24,7 @@ from ..auth.api_token import APITokenAuth
 from ..exceptions import (
     AuthenticationError,
     AuthorizationError,
+    ConfigurationError,
     ConflictError,
     NotFoundError,
     RateLimitError,
@@ -83,7 +88,7 @@ class BaseClient:
 
         # Validate authentication
         if not self.auth.validate_token():
-            raise ValueError("API token is required and cannot be empty")
+            raise ConfigurationError("API token is required and cannot be empty")
 
         # API version detection (for backward compatibility)
         self._api_version: Literal["v4", "v5"] | None = (
@@ -458,3 +463,87 @@ class BaseClient:
 
         # Media list follows standard collection format
         return self._parse_collection_response(response_data)
+
+    def _parse_content_types_response(
+        self,
+        response_data: dict[str, Any],
+        include_plugins: bool = False,
+    ) -> list["ContentTypeListItem"]:
+        """Parse content-type-builder content types response.
+
+        Args:
+            response_data: Raw JSON response from content-type-builder
+            include_plugins: Whether to include plugin content types
+
+        Returns:
+            List of ContentTypeListItem instances
+        """
+        from ..models.content_type import ContentTypeListItem
+
+        data = response_data.get("data", [])
+        result = []
+
+        for item in data:
+            uid = item.get("uid", "")
+            # Filter out plugin content types if not requested
+            if not include_plugins and uid.startswith("plugin::"):
+                continue
+
+            try:
+                content_type = ContentTypeListItem.model_validate(item)
+                result.append(content_type)
+            except Exception:
+                # Skip malformed items
+                logger.warning(f"Failed to parse content type: {uid}")
+                continue
+
+        return result
+
+    def _parse_components_response(
+        self,
+        response_data: dict[str, Any],
+    ) -> list["ComponentListItem"]:
+        """Parse content-type-builder components response.
+
+        Args:
+            response_data: Raw JSON response from content-type-builder
+
+        Returns:
+            List of ComponentListItem instances
+        """
+        from ..models.content_type import ComponentListItem
+
+        data = response_data.get("data", [])
+        result = []
+
+        for item in data:
+            uid = item.get("uid", "")
+            try:
+                component = ComponentListItem.model_validate(item)
+                result.append(component)
+            except Exception:
+                # Skip malformed items
+                logger.warning(f"Failed to parse component: {uid}")
+                continue
+
+        return result
+
+    def _parse_content_type_schema_response(
+        self,
+        response_data: dict[str, Any],
+    ) -> "CTBContentTypeSchema":
+        """Parse content-type-builder single content type schema response.
+
+        Args:
+            response_data: Raw JSON response from content-type-builder
+
+        Returns:
+            CTBContentTypeSchema instance
+
+        Raises:
+            ValidationError: If response cannot be parsed
+        """
+        from ..models.content_type import ContentTypeSchema as CTBContentTypeSchema
+
+        data = response_data.get("data", response_data)
+        return CTBContentTypeSchema.model_validate(data)

strapi_kit/client/sync_client.py

@@ -7,7 +7,11 @@ and applications that don't require concurrency.
 import logging
 from collections.abc import Callable
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..models.content_type import ComponentListItem, ContentTypeListItem
+    from ..models.content_type import ContentTypeSchema as CTBContentTypeSchema
 
 import httpx
 
@@ -978,3 +982,85 @@ class SyncClient(BaseClient):
             succeeded=success_count,
             failed=len(failures),
         )
+
+    # Content-Type Builder API
+
+    def get_content_types(
+        self,
+        *,
+        include_plugins: bool = False,
+    ) -> list["ContentTypeListItem"]:
+        """List all content types from Content-Type Builder API.
+
+        Retrieves schema information for all content types defined in Strapi.
+
+        Args:
+            include_plugins: Whether to include plugin content types
+                            (e.g., users-permissions). Defaults to False.
+
+        Returns:
+            List of ContentTypeListItem with uid, kind, info, and attributes
+
+        Examples:
+            >>> # Get only API content types
+            >>> content_types = client.get_content_types()
+            >>> for ct in content_types:
+            ...     print(f"{ct.uid}: {ct.info.display_name}")
+            api::article.article: Article
+            api::category.category: Category
+
+            >>> # Include plugin content types
+            >>> all_types = client.get_content_types(include_plugins=True)
+            >>> plugin_types = [ct for ct in all_types if ct.uid.startswith("plugin::")]
+        """
+
+        raw_response = self.get("content-type-builder/content-types")
+        return self._parse_content_types_response(raw_response, include_plugins)
+
+    def get_components(self) -> list["ComponentListItem"]:
+        """List all components from Content-Type Builder API.
+
+        Retrieves schema information for all components defined in Strapi.
+
+        Returns:
+            List of ComponentListItem with uid, category, info, and attributes
+
+        Examples:
+            >>> components = client.get_components()
+            >>> for comp in components:
+            ...     print(f"{comp.category}/{comp.uid}: {comp.info.display_name}")
+            shared/shared.seo: SEO
+            blocks/blocks.hero: Hero Section
+        """
+
+        raw_response = self.get("content-type-builder/components")
+        return self._parse_components_response(raw_response)
+
+    def get_content_type_schema(self, uid: str) -> "CTBContentTypeSchema":
+        """Get full schema for a specific content type.
+
+        Retrieves detailed schema information including all field configurations.
+
+        Args:
+            uid: Content type UID (e.g., "api::article.article")
+
+        Returns:
+            CTBContentTypeSchema with complete field definitions
+
+        Raises:
+            NotFoundError: If content type doesn't exist
+
+        Examples:
+            >>> schema = client.get_content_type_schema("api::article.article")
+            >>> schema.info.display_name
+            'Article'
+            >>> schema.attributes["title"]["type"]
+            'string'
+            >>> schema.is_relation_field("author")
+            True
+            >>> schema.get_relation_target("author")
+            'api::author.author'
+        """
+
+        raw_response = self.get(f"content-type-builder/content-types/{uid}")
+        return self._parse_content_type_schema_response(raw_response)

strapi_kit/config_provider.py

@@ -9,25 +9,10 @@ from typing import Any
 
 from pydantic import SecretStr, ValidationError
 
-from .exceptions import StrapiError
+from .exceptions import ConfigurationError
 from .models.config import RetryConfig, StrapiConfig
 
 
-class ConfigurationError(StrapiError):
-    """Raised when configuration cannot be loaded or is invalid.
-
-    Inherits from StrapiError for consistent exception handling.
-    """
-
-    def __init__(self, message: str) -> None:
-        """Initialize ConfigurationError.
-
-        Args:
-            message: Human-readable error message
-        """
-        super().__init__(message, details=None)
-
-
 class ConfigFactory:
     """Factory for creating StrapiConfig instances from various sources.
 

strapi_kit/exceptions/__init__.py

@@ -3,6 +3,7 @@
 from .errors import (
     AuthenticationError,
     AuthorizationError,
+    ConfigurationError,
     ConflictError,
     ConnectionError,
     FormatError,
@@ -20,6 +21,7 @@ from .errors import (
 
 __all__ = [
     "StrapiError",
+    "ConfigurationError",
     "AuthenticationError",
     "AuthorizationError",
     "NotFoundError",

strapi_kit/exceptions/errors.py

@@ -32,6 +32,19 @@ class StrapiError(Exception):
         return self.message
 
 
+class ConfigurationError(StrapiError):
+    """Raised when configuration is invalid or cannot be loaded.
+
+    This includes:
+    - Missing required configuration values
+    - Invalid configuration values (wrong types, out of range)
+    - Invalid URLs or authentication tokens
+    - Failed .env file loading
+    """
+
+    pass
+
+
 # HTTP Status Code Related Errors
 
 

strapi_kit/export/exporter.py

@@ -11,7 +11,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 from strapi_kit.cache.schema_cache import InMemorySchemaCache
-from strapi_kit.exceptions import ImportExportError
+from strapi_kit.exceptions import ImportExportError, ValidationError
 from strapi_kit.export.media_handler import MediaHandler
 from strapi_kit.export.relation_resolver import RelationResolver
 from strapi_kit.models.export_format import (
@@ -78,7 +78,7 @@ class StrapiExporter:
             ExportData containing all exported content
 
         Raises:
-            ValueError: If include_media=True but media_dir is not provided
+            ValidationError: If include_media=True but media_dir is not provided
             ImportExportError: If export fails
 
         Example:
@@ -89,7 +89,7 @@ class StrapiExporter:
             >>> print(f"Exported {export_data.get_entity_count()} entities")
         """
         if include_media and media_dir is None:
-            raise ValueError("media_dir must be provided when include_media=True")
+            raise ValidationError("media_dir must be provided when include_media=True")
 
         try:
             # Create metadata
@@ -161,8 +161,9 @@ class StrapiExporter:
                         "Exporting media files",
                     )
 
-                # media_dir is guaranteed non-None here (validated at method start)
-                assert media_dir is not None
+                # Type guard: media_dir validated at method start (line 91-92)
+                if media_dir is None:
+                    raise ValidationError("media_dir must be provided when include_media=True")
                 self._export_media(
                     export_data, media_dir, progress_callback, media_ids=all_media_ids
                 )

strapi_kit/models/__init__.py

@@ -5,6 +5,9 @@ Includes configuration models and request/response models for Strapi API interac
 
 from .bulk import BulkOperationFailure, BulkOperationResult
 from .config import RetryConfig, StrapiConfig
+from .content_type import ComponentListItem, ContentTypeListItem
+from .content_type import ContentTypeInfo as CTBContentTypeInfo
+from .content_type import ContentTypeSchema as CTBContentTypeSchema
 from .enums import FilterOperator, PublicationState, SortDirection
 from .export_format import ExportData, ExportedEntity, ExportedMediaFile, ExportMetadata
 from .import_options import ConflictResolution, ImportOptions, ImportResult
@@ -101,4 +104,9 @@ __all__ = [
     "FieldSchema",
     "FieldType",
     "RelationType",
+    # Content-Type Builder models
+    "CTBContentTypeInfo",
+    "CTBContentTypeSchema",
+    "ContentTypeListItem",
+    "ComponentListItem",
 ]

strapi_kit/models/content_type.py

@@ -0,0 +1,148 @@
+"""Content-Type Builder API response models.
+
+This module provides Pydantic models for parsing responses from
+Strapi's Content-Type Builder API.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ContentTypeInfo(BaseModel):
+    """Content type info metadata.
+
+    Contains display and naming information for a content type.
+    """
+
+    display_name: str = Field(alias="displayName")
+    singular_name: str | None = Field(None, alias="singularName")
+    plural_name: str | None = Field(None, alias="pluralName")
+    description: str | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class ContentTypeListItem(BaseModel):
+    """Content type list item from Content-Type Builder API.
+
+    Represents a single content type in the list response.
+    """
+
+    uid: str
+    kind: str = "collectionType"
+    info: ContentTypeInfo
+    attributes: dict[str, Any] = Field(default_factory=dict)
+    plugin_options: dict[str, Any] | None = Field(None, alias="pluginOptions")
+
+    model_config = {"populate_by_name": True}
+
+
+class ComponentListItem(BaseModel):
+    """Component list item from Content-Type Builder API.
+
+    Represents a single component in the list response.
+    """
+
+    uid: str
+    category: str
+    info: ContentTypeInfo
+    attributes: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"populate_by_name": True}
+
+
+class ContentTypeSchema(BaseModel):
+    """Full content type schema from Content-Type Builder API.
+
+    Contains complete schema information including all attributes
+    and their configurations.
+    """
+
+    uid: str
+    kind: str = "collectionType"
+    info: ContentTypeInfo
+    attributes: dict[str, Any] = Field(default_factory=dict)
+    plugin_options: dict[str, Any] | None = Field(None, alias="pluginOptions")
+    options: dict[str, Any] | None = None
+
+    model_config = {"populate_by_name": True}
+
+    @property
+    def display_name(self) -> str:
+        """Get the display name from info."""
+        return self.info.display_name
+
+    @property
+    def singular_name(self) -> str | None:
+        """Get the singular name from info."""
+        return self.info.singular_name
+
+    @property
+    def plural_name(self) -> str | None:
+        """Get the plural name from info."""
+        return self.info.plural_name
+
+    def get_field_type(self, field_name: str) -> str | None:
+        """Get the type of a specific field.
+
+        Args:
+            field_name: Name of the field
+
+        Returns:
+            Field type string or None if not found
+        """
+        field = self.attributes.get(field_name)
+        if isinstance(field, dict):
+            return field.get("type")
+        return None
+
+    def is_relation_field(self, field_name: str) -> bool:
+        """Check if a field is a relation.
+
+        Args:
+            field_name: Name of the field
+
+        Returns:
+            True if field is a relation
+        """
+        return self.get_field_type(field_name) == "relation"
+
+    def is_component_field(self, field_name: str) -> bool:
+        """Check if a field is a component.
+
+        Args:
+            field_name: Name of the field
+
+        Returns:
+            True if field is a component
+        """
+        return self.get_field_type(field_name) == "component"
+
+    def get_relation_target(self, field_name: str) -> str | None:
+        """Get the target content type for a relation field.
+
+        Args:
+            field_name: Name of the relation field
+
+        Returns:
+            Target content type UID or None
+        """
+        field = self.attributes.get(field_name)
+        if isinstance(field, dict) and field.get("type") == "relation":
+            return field.get("target")
+        return None
+
+    def get_component_uid(self, field_name: str) -> str | None:
+        """Get the component UID for a component field.
+
+        Args:
+            field_name: Name of the component field
+
+        Returns:
+            Component UID or None
+        """
+        field = self.attributes.get(field_name)
+        if isinstance(field, dict) and field.get("type") == "component":
+            return field.get("component")
+        return None

strapi_kit/models/export_format.py

@@ -10,6 +10,8 @@ from typing import Any
 
 from pydantic import BaseModel, Field, field_validator
 
+from strapi_kit.exceptions import FormatError
+
 from .schema import ContentTypeSchema
 
 
@@ -117,13 +119,13 @@ class ExportedMediaFile(BaseModel):
             The validated path
 
         Raises:
-            ValueError: If path contains traversal sequences or is absolute
+            FormatError: If path contains traversal sequences or is absolute
         """
         if ".." in v or v.startswith("/") or v.startswith("\\"):
-            raise ValueError("local_path must be relative without path traversal")
+            raise FormatError("local_path must be relative without path traversal")
         # Block Windows drive-letter absolute paths (e.g., C:\, D:/)
         if PureWindowsPath(v).is_absolute():
-            raise ValueError("local_path must be relative without path traversal")
+            raise FormatError("local_path must be relative without path traversal")
         return v
 
 

strapi_kit/models/request/query.py

@@ -36,6 +36,7 @@ from __future__ import annotations
 import copy
 from typing import Any
 
+from strapi_kit.exceptions import ValidationError
 from strapi_kit.models.enums import PublicationState, SortDirection
 from strapi_kit.models.request.fields import FieldSelection
 from strapi_kit.models.request.filters import FilterBuilder
@@ -220,7 +221,9 @@ class StrapiQuery:
             Self for method chaining
 
         Raises:
-            ValueError: If mixing page-based and offset-based parameters
+            strapi_kit.exceptions.ValidationError: If mixing page-based and
+                offset-based parameters, or if pagination values are invalid
+                (page < 1, page_size < 1, start < 0, limit < 1)
 
         Examples:
             >>> # Page-based
@@ -234,15 +237,15 @@ class StrapiQuery:
         offset_based = start is not None or limit is not None
 
         if page_based and offset_based:
-            raise ValueError("Cannot mix page-based and offset-based pagination")
+            raise ValidationError("Cannot mix page-based and offset-based pagination")
 
         if page_based:
             # Validate page value if explicitly provided
             if page is not None and page < 1:
-                raise ValueError("page must be >= 1")
+                raise ValidationError("page must be >= 1")
             # Validate page_size value if explicitly provided
             if page_size is not None and page_size < 1:
-                raise ValueError("page_size must be >= 1")
+                raise ValidationError("page_size must be >= 1")
             self._pagination = PagePagination(
                 page=1 if page is None else page,
                 page_size=25 if page_size is None else page_size,
@@ -251,10 +254,10 @@ class StrapiQuery:
         elif offset_based:
             # Validate start value if explicitly provided
             if start is not None and start < 0:
-                raise ValueError("start must be >= 0")
+                raise ValidationError("start must be >= 0")
             # Validate limit value if explicitly provided
             if limit is not None and limit < 1:
-                raise ValueError("limit must be >= 1")
+                raise ValidationError("limit must be >= 1")
             self._pagination = OffsetPagination(
                 start=0 if start is None else start,
                 limit=25 if limit is None else limit,