shopware-api-client 1.0.118__py3-none-any.whl → 1.1.1__py3-none-any.whl

shopware_api_client/base.py

@@ -29,6 +29,7 @@ from pydantic import (
     Field,
     ValidationError,
     model_serializer,
+    PydanticUserError,
 )
 from pydantic.alias_generators import to_camel
 from pydantic.main import IncEx
@@ -47,6 +48,7 @@ from .exceptions import (
     SWFilterException,
     SWNoClientProvided,
 )
+from .fieldsets import FieldSetBase
 from .logging import logger
 
 if TYPE_CHECKING:
@@ -54,8 +56,12 @@ if TYPE_CHECKING:
 
 APPLICATION_JSON = "application/json"
 
-EndpointClass = TypeVar("EndpointClass", bound="EndpointBase[Any]")
-ModelClass = TypeVar("ModelClass", bound="ApiModelBase[Any]")
+EndpointClass = TypeVar("EndpointClass", bound="EndpointBase")
+AdminEndpointClass = TypeVar("AdminEndpointClass", bound="AdminEndpoint")
+ModelClass = TypeVar("ModelClass", bound="ApiModelBase")
+AdminModelClass = TypeVar("AdminModelClass", bound="AdminModel")
+FieldSet = TypeVar("FieldSet", bound="FieldSetBase")
+
 RETRY_CACHE_KEY = "shopware-api-client:retry:{url}:{method}"
 HEADER_X_RATE_LIMIT_LIMIT = "X-Rate-Limit-Limit"
 HEADER_X_RATE_LIMIT_REMAINING = "X-Rate-Limit-Remaining"
@@ -64,11 +70,11 @@ HEADER_X_RATE_LIMIT_RESET = "X-Rate-Limit-Reset"
 
 class ConfigBase:
     def __init__(
-        self,
-        url: str,
-        retry_after_threshold: int = 60,
-        redis_client: "Redis | None" = None,
-        local_cache_cleanup_cycle_seconds: int = 10,
+            self,
+            url: str,
+            retry_after_threshold: int = 60,
+            redis_client: "Redis | None" = None,
+            local_cache_cleanup_cycle_seconds: int = 10,
     ) -> None:
         self.url = url.rstrip("/")
         self.retry_after_threshold = retry_after_threshold
@@ -140,7 +146,7 @@ class ClientBase:
 
     async def sleep_and_increment(self, retry_wait_base: int, retry_count: int) -> int:
         retry_count += 1
-        sleep_and_increment = retry_wait_base**retry_count
+        sleep_and_increment = retry_wait_base ** retry_count
         logger.debug(f"Try failed, retrying in {sleep_and_increment} seconds.")
         await asyncio.sleep(sleep_and_increment)
         return retry_count
@@ -285,10 +291,10 @@ class ClientBase:
                     error = error.errors[0]
 
                 if isinstance(error, SWAPIErrorList):
-                    if any([isinstance(err, no_retry_errors) for err in error.errors]):
+                    if any(isinstance(err, no_retry_errors) for err in error.errors):
                         raise error
 
-                    if not any([isinstance(err, retry_errors) for err in error.errors]):
+                    if not any(isinstance(err, retry_errors) for err in error.errors):
                         raise error
 
                 elif isinstance(error, no_retry_errors) or not isinstance(error, retry_errors):
@@ -310,7 +316,7 @@ class ClientBase:
                         exception = SWAPIError.from_response(response)
                         # prefix details with x-trace-header to
                         exception.detail = (
-                            f"x-trace-id: {str(response.headers.get('x-trace-id', 'not-set'))}" + exception.detail
+                                f"x-trace-id: {str(response.headers.get('x-trace-id', 'not-set'))}" + exception.detail
                         )
                         raise exception
 
@@ -343,28 +349,51 @@ class ClientBase:
         await self.http_client.aclose()
 
     async def bulk_upsert(
-        self,
-        name: str,
-        objs: list[ModelClass] | list[dict[str, Any]],
-        fail_silently: bool = False,
-        **request_kwargs: Any,
+            self,
+            name: str,
+            objs: list[ModelClass] | list[dict[str, Any]],
+            fail_silently: bool = False,
+            **request_kwargs: Any,
     ) -> dict[str, Any]:
         raise SWAPIException("bulk_upsert is only supported in the admin API")
 
     async def bulk_delete(
-        self,
-        name: str,
-        objs: list[ModelClass] | list[dict[str, Any]],
-        fail_silently: bool = False,
-        **request_kwargs: Any,
+            self,
+            name: str,
+            objs: list[ModelClass] | list[dict[str, Any]],
+            fail_silently: bool = False,
+            **request_kwargs: Any,
     ) -> dict[str, Any]:
         raise SWAPIException("bulk_delete is only supported in the admin API")
 
-    def set_language(self, language_id: IdField | None) -> None:
+    def set_language(self, language_id: "IdField | None") -> None:
         self.language_id = language_id
 
 
-class ApiModelBase(BaseModel, Generic[EndpointClass]):
+class EndpointMixin(Generic[EndpointClass]):
+    def __init__(self, client: ClientBase | None = None, **kwargs: dict[str, Any]) -> None:
+        self._client: ClientBase | None = client
+        super().__init__(**kwargs)
+
+    @classmethod
+    def using(cls, client: ClientBase) -> EndpointClass:
+        # we want a fresh endpoint
+        endpoint: EndpointClass = getattr(client, cls._identifier.get_default()).__class__(client)  # type: ignore
+        return endpoint
+
+    def _get_client(self) -> ClientBase:
+        if self._client is None:
+            raise SWNoClientProvided("Model has no api client set. Use `using` to set a client.")
+        return self._client
+
+    def _get_endpoint(self) -> EndpointClass:
+        # we want a fresh endpoint
+        client = self._get_client()
+        endpoint: EndpointClass = getattr(client, self._identifier).__class__(client)  # type: ignore
+        return endpoint
+
+
+class ApiModelBase(BaseModel):
     model_config = ConfigDict(
         alias_generator=AliasGenerator(
             validation_alias=lambda field_name: AliasChoices(field_name, to_camel(field_name)),
@@ -373,13 +402,27 @@ class ApiModelBase(BaseModel, Generic[EndpointClass]):
         validate_assignment=True,
     )
 
-    id: IdField | None = None
-    created_at: AwareDatetime = Field(default_factory=lambda: datetime.now(UTC), exclude=True)
+    id: "IdField | None" = None
+    version_id: IdField | None = None
+    translated: dict[str, Any] | list[Any] | None = None
+    created_at: AwareDatetime | None = Field(default_factory=lambda: datetime.now(UTC), exclude=True)
     updated_at: AwareDatetime | None = Field(default=None, exclude=True)
 
     def __init__(self, client: ClientBase | None = None, **kwargs: dict[str, Any]) -> None:
-        super().__init__(**kwargs)
-        self._client = client
+        self._insert_translations(
+            data=kwargs,
+            translations=kwargs.get("translated")
+        )
+
+        try:
+            super().__init__(**kwargs)
+        except PydanticUserError:
+            self.model_rebuild()
+            super().__init__(**kwargs)
+
+        # Pydantic doesn't do a good job at calling the parents, so we have to help
+        if isinstance(self, EndpointMixin):
+            EndpointMixin.__init__(self, client=client)
 
     def __setattr__(self, name: str, value: Any) -> Any:
         from .endpoints.relations import ForeignRelation, ManyRelation
@@ -410,6 +453,17 @@ class ApiModelBase(BaseModel, Generic[EndpointClass]):
 
         return super().__getattribute__(name)
 
+    @staticmethod
+    def _insert_translations(data: dict[str, Any], translations: dict[str, Any] | list[Any] | None) -> dict[str, Any]:
+        if not isinstance(translations, dict):
+            return data
+
+        for key, value in translations.items():
+            if value and data.get(key) is None:
+                data[key] = value
+
+        return data
+
     @model_serializer(mode="wrap")
     def ser_model(self, serializer: Callable[..., dict[str, Any]]) -> dict[str, Any]:
         from .endpoints.relations import ForeignRelation, ManyRelation
@@ -429,24 +483,14 @@ class ApiModelBase(BaseModel, Generic[EndpointClass]):
 
         return ser_dict
 
-    @classmethod
-    def using(cls: type[Self], client: ClientBase) -> EndpointClass:
-        # we want a fresh endpoint
-        endpoint: EndpointClass = getattr(client, cls._identifier.get_default()).__class__(client)  # type: ignore
-        return endpoint
 
-    def _get_client(self) -> ClientBase:
-        if self._client is None:
-            raise SWNoClientProvided("Model has no api client set. Use `using` to set a client.")
-        return self._client
-
-    def _get_endpoint(self) -> EndpointClass:
-        # we want a fresh endpoint
-        client = self._get_client()
-        endpoint: EndpointClass = getattr(client, self._identifier).__class__(client)  # type: ignore
-        return endpoint
+class AdminModel(ApiModelBase, EndpointMixin[AdminEndpointClass], Generic[AdminEndpointClass]):
+    def __init__(self, client: ClientBase | None = None, **kwargs: dict[str, Any]) -> None:
+        super().__init__(client, **kwargs)
 
-    async def save(self, force_insert: bool = False, update_fields: IncEx | None = None) -> Self | dict | None:
+    async def save(
+            self, force_insert: bool = False, update_fields: IncEx | None = None
+    ) -> "AdminModel[Any] | dict | None":
         endpoint = self._get_endpoint()
 
         if force_insert or self.id is None:
@@ -466,15 +510,46 @@ class ApiModelBase(BaseModel, Generic[EndpointClass]):
         return await endpoint.delete(pk=self.id)
 
 
-class EndpointBase(Generic[ModelClass]):
+class CustomFieldsMixin(BaseModel):
+    custom_fields: dict[str, Any] | None = Field(default=None)
+
+
+class EndpointBase:
     name: str
     path: str
-    model_class: Type[ModelClass]
     raw: bool
+    search_prefix: str = "/search"
 
-    def __init__(self, client: ClientBase):
+    def __init__(self, client: ClientBase, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
         self.client = client
         self.raw = client.raw
+
+    def _parse_data(self, response_dict: dict[str, Any]) -> list[dict[str, Any]]:
+        if "data" in response_dict:
+            key = "data"
+        elif "elements" in response_dict:
+            key = "elements"
+        else:
+            key = None
+
+        data: list[dict[str, Any]] | dict[str, Any] = response_dict[key] if key else response_dict
+
+        if isinstance(data, dict):
+            return [data]
+
+        return data
+
+    def _parse_data_single(self, reponse_dict: dict[str, Any]) -> dict[str, Any]:
+        return self._parse_data(reponse_dict)[0]
+
+
+class EndpointSearchMixin(Generic[ModelClass]):
+    model_class: Type[ModelClass]
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        super().__init__(*args, **kwargs)
+
         self._filter: list[dict[str, Any]] = []
         self._limit: int | None = None
         self._page: int | None = None
@@ -533,24 +608,129 @@ class EndpointBase(Generic[ModelClass]):
         else:
             return self.model_class.model_fields[name].serialization_alias or name
 
+    def select_related(self, **kwargs: Any) -> Self:
+        self._associations.update({self._serialize_field_name(field): data for field, data in kwargs.items()})
+        return self
+
+    def only(self, **kwargs: list[str]) -> Self:
+        for field, data in kwargs.items():
+            self._includes[self._serialize_field_name(field)] = [self._serialize_field_name(d) for d in data]
+
+        return self
+
+    def filter(self, **kwargs: Any) -> Self:
+        for key, value in kwargs.items():
+            filter_term = ""
+            filter_type = "equals"
+
+            field_parts = key.split("__")
+
+            if len(field_parts) > 1:
+                filter_term = field_parts[-1]
+
+                match filter_term:
+                    case "in":
+                        filter_type = "equalsAny"
+                    case "contains":
+                        filter_type = "contains"
+                    case "gt":
+                        filter_type = "range"
+                    case "gte":
+                        filter_type = "range"
+                    case "lt":
+                        filter_type = "range"
+                    case "lte":
+                        filter_type = "range"
+                    case "range":
+                        filter_type = "range"
+                    case "startswith":
+                        filter_type = "prefix"
+                    case "endswith":
+                        filter_type = "suffix"
+                    case _:
+                        filter_term = ""
+
+            if field_parts[0] not in self.model_class.model_fields:
+                raise SWFilterException(
+                    f"Unknown Field: {field_parts[0]}. Available fields: {self.model_class.model_fields.keys()}"
+                )
+
+            if filter_term != "":
+                field_parts = field_parts[:-1]
+
+            if len(field_parts) >= 2:
+                field = "%s.%s" % (
+                    self._serialize_field_name(field_parts[0]),
+                    ".".join(field_parts[1:]),
+                )
+            else:
+                field = self._serialize_field_name(field_parts[0])
+
+            parameters = {}
+
+            # range has additional parameters
+            if filter_type == "range":
+                if filter_term == "range":
+                    parameters = {"gte": value[0], "lte": value[1]}
+                else:
+                    parameters = {filter_term: value}
+
+            self._filter.append({"type": filter_type, "field": field, "value": value, "parameters": parameters})
+
+        return self
+
+    def limit(self, count: int | None) -> "Self":
+        self._limit = count
+        return self
+
+    def page(self, num: int | None) -> "Self":
+        self._page = num
+        return self
+
+    def order_by(self, fields: str | tuple[str]) -> "Self":
+        if isinstance(fields, str):
+            fields = (fields,)
+
+        for field in fields:
+            if field.startswith("-"):
+                field = field[1:]
+                order = "DESC"
+            else:
+                order = "ASC"
+
+            if field not in self.model_class.model_fields:
+                raise SWFilterException(
+                    f"Unknown Field: {field}. Available fields: {self.model_class.model_fields.keys()}"
+                )
+            else:
+                field = self._serialize_field_name(field)
+
+            self._sort.append({"field": field, "order": order})
+
+        return self
+
+
+class AdminEndpoint(EndpointBase, EndpointSearchMixin, Generic[AdminModelClass]):
+    model_class: Type[AdminModelClass]
+
     @overload
-    def _parse_response(self, data: list[dict[str, Any]]) -> list[ModelClass]:
+    def _parse_response(self, data: list[dict[str, Any]]) -> list[AdminModelClass]:
         # typing overload
         ...
 
     @overload
-    def _parse_response(self, data: dict[str, Any]) -> ModelClass:
+    def _parse_response(self, data: dict[str, Any]) -> AdminModelClass:
         # typing overload
         ...
 
-    def _parse_response(self, data: list[dict[str, Any]] | dict[str, Any]) -> list[ModelClass] | ModelClass:
+    def _parse_response(self, data: list[dict[str, Any]] | dict[str, Any]) -> list[AdminModelClass] | AdminModelClass:
         single = False
 
         if isinstance(data, dict):
             single = True
             data = [data]
 
-        result_list: list[ModelClass] = []
+        result_list: list[AdminModelClass] = []
         errors = []
 
         for entry in data:
@@ -582,31 +762,13 @@ class EndpointBase(Generic[ModelClass]):
 
         return result_list
 
-    def _parse_data(self, response_dict: dict[str, Any]) -> list[dict[str, Any]]:
-        if "data" in response_dict:
-            key = "data"
-        elif "elements" in response_dict:
-            key = "elements"
-        else:
-            key = None
-
-        data: list[dict[str, Any]] | dict[str, Any] = response_dict[key] if key else response_dict
-
-        if isinstance(data, dict):
-            return [data]
-
-        return data
-
-    def _parse_data_single(self, reponse_dict: dict[str, Any]) -> dict[str, Any]:
-        return self._parse_data(reponse_dict)[0]
-
-    async def all(self) -> list[ModelClass] | list[dict[str, Any]]:
+    async def all(self) -> list[AdminModelClass] | list[dict[str, Any]]:
         data = self._get_data_dict()
 
         if self._is_search_query():
-            result = await self.client.post(f"/search{self.path}", json=data)
+            result = await self.client.post(f"{self.search_prefix}{self.path}", json=data)
         else:
-            result = await self.client.get(f"{self.path}", params=data)
+            result = await self.client.get(self.path, params=data)
 
         result_data: list[dict[str, Any]] = self._parse_data(result.json())
 
@@ -617,7 +779,7 @@ class EndpointBase(Generic[ModelClass]):
 
         return self._parse_response(result_data)
 
-    async def get(self, pk: str) -> ModelClass | dict[str, Any]:
+    async def get(self, pk: str) -> AdminModelClass | dict[str, Any]:
         result = await self.client.get(f"{self.path}/{pk}")
         result_data: dict[str, Any] = self._parse_data_single(result.json())
 
@@ -627,8 +789,8 @@ class EndpointBase(Generic[ModelClass]):
         return self._parse_response(result_data)
 
     async def update(
-        self, pk: str, obj: ModelClass | dict[str, Any], update_fields: IncEx | None = None
-    ) -> ModelClass | dict[str, Any] | None:
+            self, pk: str, obj: AdminModelClass | dict[str, Any], update_fields: IncEx | None = None
+    ) -> AdminModelClass | dict[str, Any] | None:
         if isinstance(obj, ApiModelBase):
             data = obj.model_dump_json(by_alias=True, include=update_fields)
         else:
@@ -646,7 +808,7 @@ class EndpointBase(Generic[ModelClass]):
 
         return self._parse_response(result_data)
 
-    async def first(self) -> ModelClass | dict[str, Any] | None:
+    async def first(self) -> AdminModelClass | dict[str, Any] | None:
         self._limit = 1
         result = await self.all()
 
@@ -658,7 +820,7 @@ class EndpointBase(Generic[ModelClass]):
 
         return result[0]
 
-    async def create(self, obj: ModelClass | dict[str, Any]) -> ModelClass | dict[str, Any] | None:
+    async def create(self, obj: AdminModelClass | dict[str, Any]) -> AdminModelClass | dict[str, Any] | None:
         if isinstance(obj, ApiModelBase):
             data = obj.model_dump_json(by_alias=True)
         else:
@@ -684,7 +846,7 @@ class EndpointBase(Generic[ModelClass]):
 
         return False
 
-    async def get_related(self, parent: ModelClass, relation: str) -> list[ModelClass] | list[dict[str, Any]]:
+    async def get_related(self, parent: AdminModelClass, relation: str) -> list[AdminModelClass] | list[dict[str, Any]]:
         parent_endpoint = parent._get_endpoint()
         result = await self.client.get(f"{parent_endpoint.path}/{parent.id}/{relation}")
         result_data: list[dict[str, Any]] = self._parse_data(result.json())
@@ -694,133 +856,121 @@ class EndpointBase(Generic[ModelClass]):
 
         return self._parse_response(result_data)
 
-    def select_related(self, **kwargs: Any) -> Self:
-        self._associations.update({self._serialize_field_name(field): data for field, data in kwargs.items()})
-        return self
+    async def bulk_upsert(
+            self, objs: list[AdminModelClass] | list[dict[str, Any]], fail_silently: bool = False, **request_kwargs: Any
+    ) -> dict[str, Any]:
+        return await self.client.bulk_upsert(name=self.name, objs=objs, fail_silently=fail_silently, **request_kwargs)
 
-    def only(self, **kwargs: list[str]) -> Self:
-        for field, data in kwargs.items():
-            self._includes[self._serialize_field_name(field)] = [self._serialize_field_name(d) for d in data]
+    async def bulk_delete(
+            self, objs: list[AdminModelClass] | list[dict[str, Any]], fail_silently: bool = False, **request_kwargs: Any
+    ) -> dict[str, Any]:
+        return await self.client.bulk_delete(name=self.name, objs=objs, fail_silently=fail_silently, **request_kwargs)
 
-        return self
+    async def iter(self, batch_size: int = 100) -> AsyncGenerator[AdminModelClass | dict[str, Any], None]:
+        self._limit = batch_size
+        data = self._get_data_dict()
+        page = 1
 
-    def filter(self, **kwargs: Any) -> Self:
-        for key, value in kwargs.items():
-            filter_term = ""
-            filter_type = "equals"
+        if self._is_search_query():
+            url = f"/search{self.path}"
+        else:
+            url = self.path
 
-            field_parts = key.split("__")
+        while True:
+            data["page"] = page
+            if self._is_search_query():
+                result = await self.client.post(url, json=data)
+            else:
+                result = await self.client.get(url, params=data)
 
-            if len(field_parts) > 1:
-                filter_term = field_parts[-1]
+            result_dict: dict[str, Any] = result.json()
+            result_data: list[dict[str, Any]] = self._parse_data(result_dict)
 
-                match filter_term:
-                    case "in":
-                        filter_type = "equalsAny"
-                    case "contains":
-                        filter_type = "contains"
-                    case "gt":
-                        filter_type = "range"
-                    case "gte":
-                        filter_type = "range"
-                    case "lt":
-                        filter_type = "range"
-                    case "lte":
-                        filter_type = "range"
-                    case "range":
-                        filter_type = "range"
-                    case "startswith":
-                        filter_type = "prefix"
-                    case "endswith":
-                        filter_type = "suffix"
-                    case _:
-                        filter_term = ""
+            for entry in result_data:
+                if self.raw:
+                    yield entry
+                else:
+                    yield self._parse_response(entry)
 
-            if field_parts[0] not in self.model_class.model_fields:
-                raise SWFilterException(
-                    f"Unknown Field: {field_parts[0]}. Available fields: {self.model_class.model_fields.keys()}"
-                )
+            if len(result_data) >= self._limit:
+                page += 1
+            else:
+                break
 
-            if filter_term != "":
-                field_parts = field_parts[:-1]
 
-            if len(field_parts) >= 2:
-                field = "%s.%s" % (
-                    self._serialize_field_name(field_parts[0]),
-                    ".".join(field_parts[1:]),
-                )
-            else:
-                field = self._serialize_field_name(field_parts[0])
+class StoreEndpoint(EndpointBase):
+    @overload
+    @staticmethod
+    def _parse_response(data: list[dict[str, Any]], cls: Type[ModelClass | FieldSet]) -> list[ModelClass | FieldSet]:
+        # typing overload
+        ...
 
-            parameters = {}
+    @overload
+    @staticmethod
+    def _parse_response(data: dict[str, Any], cls: Type[ModelClass | FieldSet]) -> ModelClass | FieldSet:
+        # typing overload
+        ...
 
-            # range has additional parameters
-            if filter_type == "range":
-                if filter_term == "range":
-                    parameters = {"gte": value[0], "lte": value[1]}
-                else:
-                    parameters = {filter_term: value}
+    @staticmethod
+    def _parse_response(
+            data: list[dict[str, Any]] | dict[str, Any], cls: Type[ModelClass | FieldSet]
+    ) -> list[ModelClass | FieldSet] | ModelClass | FieldSet:
+        single = False
 
-            self._filter.append({"type": filter_type, "field": field, "value": value, "parameters": parameters})
+        if isinstance(data, dict):
+            single = True
+            data = [data]
 
-        return self
+        result_list: list[ModelClass | FieldSet] = []
+        errors = []
 
-    async def bulk_upsert(
-        self, objs: list[ModelClass] | list[dict[str, Any]], fail_silently: bool = False, **request_kwargs: Any
-    ) -> dict[str, Any]:
-        return await self.client.bulk_upsert(name=self.name, objs=objs, fail_silently=fail_silently, **request_kwargs)
+        for entry in data:
+            try:
+                obj = cls(**entry)
+            except ValidationError as exc:
+                # catch pydantic validation errors, log faulty result with tracking data and attach to errors
+                # (errors will be raised after checking all result objects)
+                logger.error(
+                    "Invalid Shopware data",
+                    extra={"ModelClass": cls, "id": entry.get("id"), "data": entry, "detail": str(exc)},
+                )
+                errors.append(exc)
+                continue
 
-    async def bulk_delete(
-        self, objs: list[ModelClass] | list[dict[str, Any]], fail_silently: bool = False, **request_kwargs: Any
-    ) -> dict[str, Any]:
-        return await self.client.bulk_delete(name=self.name, objs=objs, fail_silently=fail_silently, **request_kwargs)
+            result_list.append(obj)
 
-    def limit(self, count: int | None) -> "Self":
-        self._limit = count
-        return self
+        if errors:
+            raise SWAPIDataValidationError(errors=errors)
 
-    def page(self, num: int | None) -> "Self":
-        self._page = num
-        return self
+        if single:
+            return result_list[0]
 
-    def order_by(self, fields: str | tuple[str]) -> "Self":
-        if isinstance(fields, str):
-            fields = (fields,)
+        return result_list
 
-        for field in fields:
-            if field.startswith("-"):
-                field = field[1:]
-                order = "DESC"
-            else:
-                order = "ASC"
 
-            if field not in self.model_class.model_fields:
-                raise SWFilterException(
-                    f"Unknown Field: {field}. Available fields: {self.model_class.model_fields.keys()}"
-                )
-            else:
-                field = self._serialize_field_name(field)
+class StoreSearchEndpoint(StoreEndpoint, EndpointSearchMixin, Generic[ModelClass]):
+    path: str
 
-            self._sort.append({"field": field, "order": order})
+    async def all(self) -> list[ModelClass] | list[dict[str, Any]]:
+        data = self._get_data_dict()
 
-        return self
+        result = await self.client.post(self.path, json=data)
+
+        result_data: list[dict[str, Any]] = result.json().get("elements", [])
+
+        if self.raw:
+            return result_data
+
+        return self._parse_response(result_data, cls=self.model_class)
 
     async def iter(self, batch_size: int = 100) -> AsyncGenerator[ModelClass | dict[str, Any], None]:
         self._limit = batch_size
         data = self._get_data_dict()
         page = 1
 
-        if self._is_search_query():
-            url = f"/search{self.path}"
-        else:
-            url = self.path
-
         while True:
             data["page"] = page
-            if self._is_search_query():
-                result = await self.client.post(url, json=data)
-            else:
-                result = await self.client.get(url, params=data)
+            result = await self.client.post(self.path, json=data)
 
             result_dict: dict[str, Any] = result.json()
             result_data: list[dict[str, Any]] = self._parse_data(result_dict)
@@ -829,9 +979,21 @@ class EndpointBase(Generic[ModelClass]):
                 if self.raw:
                     yield entry
                 else:
-                    yield self._parse_response(entry)
+                    yield self._parse_response(entry, cls=self.model_class)
 
-            if len(result_data) >= self._limit:
+            if "next" in result_dict.get("links", {}) and len(result_data) > 0:
                 page += 1
             else:
                 break
+
+    async def first(self) -> ModelClass | dict[str, Any] | None:
+        self._limit = 1
+        result = await self.all()
+
+        self._reset_endpoint()
+
+        # return None instead of an KeyError, if result is empty
+        if len(result) == 0:
+            return None
+
+        return result[0]