sqlmodel-object-helpers 0.0.4__tar.gz → 0.0.5__tar.gz

{sqlmodel_object_helpers-0.0.4 → sqlmodel_object_helpers-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-object-helpers
-Version: 0.0.4
+Version: 0.0.5
 Summary: Generic async query helpers for SQLModel: filtering, eager loading, pagination
 Project-URL: Homepage, https://github.com/itstandart/sqlmodel-object-helpers
 Project-URL: Repository, https://github.com/itstandart/sqlmodel-object-helpers
@@ -539,7 +539,34 @@ class UserFilter(BaseModel):
     posts: soh.FilterExists | None = None  # exists: bool
 ```
 
-Available: `FilterInt`, `FilterStr`, `FilterDate`, `FilterDatetime`, `FilterTimedelta`, `FilterBool`, `FilterExists`.
+Available: `FilterInt`, `FilterStr`, `FilterDate`, `FilterDatetime`, `FilterNaiveDatetime`, `FilterTimedelta`, `FilterBool`, `FilterExists`.
+
+#### Range Filters
+
+`FilterDatetimeRange` and `FilterNaiveDatetimeRange` parse a comma-separated date string into `gt`/`lt` operators:
+
+```python
+import sqlmodel_object_helpers as soh
+
+# Full range: "FROM,TO" → gt + lt
+f = soh.FilterDatetimeRange.model_validate("2026-04-01,2026-05-06")
+f.model_dump(exclude_none=True)
+# {"gt": datetime(2026, 4, 1, tzinfo=UTC), "lt": datetime(2026, 5, 6, tzinfo=UTC)}
+# SQL: WHERE field > '2026-04-01' AND field < '2026-05-06'
+
+# Open end: "FROM," → gt only
+f = soh.FilterDatetimeRange.model_validate("2026-04-01,")
+# SQL: WHERE field > '2026-04-01'
+
+# Open start: ",TO" → lt only
+f = soh.FilterDatetimeRange.model_validate(",2026-05-06")
+# SQL: WHERE field < '2026-05-06'
+```
+
+Each date part accepts ISO (`2026-04-01`, `2026-04-01T00:00:00Z`) and display format (`01.04.2026 00:00`).
+
+- `FilterDatetimeRange` — produces UTC-aware datetimes
+- `FilterNaiveDatetimeRange` — produces naive (timezone-unaware) datetimes
 
 ## Eager Loading
 
@@ -655,7 +682,8 @@ result = await soh.get_objects(session, User, order_by=order)
 
 ### Filter Types
 
-- `soh.FilterInt`, `soh.FilterStr`, `soh.FilterDate`, `soh.FilterDatetime`, `soh.FilterTimedelta`, `soh.FilterBool`, `soh.FilterExists`
+- `soh.FilterInt`, `soh.FilterStr`, `soh.FilterDate`, `soh.FilterDatetime`, `soh.FilterNaiveDatetime`, `soh.FilterTimedelta`, `soh.FilterBool`, `soh.FilterExists`
+- `soh.FilterDatetimeRange`, `soh.FilterNaiveDatetimeRange` -- Range filters that parse `"FROM,TO"` strings into `gt`/`lt` operators
 - `soh.OrderAsc`, `soh.OrderDesc`, `soh.OrderBy`
 - `soh.LogicalFilter`
 - `soh.TimeFilter` -- `created_after`, `created_before`, `updated_after`, `updated_before` with half-open interval `[after, before)`
@@ -668,7 +696,19 @@ result = await soh.get_objects(session, User, order_by=order)
 
 - `soh.Pagination` -- Request model (page, per\_page)
 - `soh.PaginationR` -- Response model (page, per\_page, total)
-- `soh.GetAllPagination[T]` -- Generic wrapper (data: list[T], pagination: PaginationR | None)
+- `soh.GetAllPagination[T]` -- Generic wrapper (table: TableMeta | None, columns: list[ColumnMeta] | None, data: list[T], pagination: PaginationR | None)
+
+### Table Metadata Types
+
+- `soh.TableMeta` -- Table-level metadata (name, header, row_link)
+- `soh.ColumnMeta` -- Column metadata (json_path, label, type, lookup_dict, lookup_path, bool_labels)
+- `soh.ColumnType` -- StrEnum of column data types (string, integer, float, boolean, date, datetime)
+- `soh.BoolLabels` -- Display labels for boolean columns (true_label, false_label)
+
+### Lookup Types
+
+- `soh.LookupMeta` -- Lookup metadata (name used as cache key, matches `ColumnMeta.lookup_dict`)
+- `soh.LookupResponse[T]` -- Generic wrapper for lookup endpoints (meta: LookupMeta, data: list[T])
 
 ### Projection Types
 
@@ -720,6 +760,19 @@ This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PAT
 - **MINOR** — new features (backwards compatible)
 - **MAJOR** — breaking changes
 
+## Changelog
+
+### 0.0.5
+
+- **FilterDatetimeRange** / **FilterNaiveDatetimeRange** — range filters that parse comma-separated date strings (`"2026-04-01,2026-05-06"`) into `gt`/`lt` operators for SQL filtering
+- **ColumnMeta** / **TableMeta** / **ColumnType** / **BoolLabels** — dynamic table metadata: backend describes columns, types, labels, lookups, and row navigation so the frontend renders any table without hardcoding
+- **GetAllPagination** — now includes optional `table` and `columns` fields for delivering table metadata alongside paginated data
+- **LookupMeta** / **LookupResponse** — standard `{meta, data}` wrapper for lookup (`_lkp`) endpoints, enabling unified frontend caching of dictionaries with `meta.name` as cache key
+
+### 0.0.4
+
+- Initial public release
+
 ## License
 
 This project is licensed under the **PolyForm Noncommercial License 1.0.0**.

{sqlmodel_object_helpers-0.0.4 → sqlmodel_object_helpers-0.0.5}/README.md

@@ -505,7 +505,34 @@ class UserFilter(BaseModel):
     posts: soh.FilterExists | None = None  # exists: bool
 ```
 
-Available: `FilterInt`, `FilterStr`, `FilterDate`, `FilterDatetime`, `FilterTimedelta`, `FilterBool`, `FilterExists`.
+Available: `FilterInt`, `FilterStr`, `FilterDate`, `FilterDatetime`, `FilterNaiveDatetime`, `FilterTimedelta`, `FilterBool`, `FilterExists`.
+
+#### Range Filters
+
+`FilterDatetimeRange` and `FilterNaiveDatetimeRange` parse a comma-separated date string into `gt`/`lt` operators:
+
+```python
+import sqlmodel_object_helpers as soh
+
+# Full range: "FROM,TO" → gt + lt
+f = soh.FilterDatetimeRange.model_validate("2026-04-01,2026-05-06")
+f.model_dump(exclude_none=True)
+# {"gt": datetime(2026, 4, 1, tzinfo=UTC), "lt": datetime(2026, 5, 6, tzinfo=UTC)}
+# SQL: WHERE field > '2026-04-01' AND field < '2026-05-06'
+
+# Open end: "FROM," → gt only
+f = soh.FilterDatetimeRange.model_validate("2026-04-01,")
+# SQL: WHERE field > '2026-04-01'
+
+# Open start: ",TO" → lt only
+f = soh.FilterDatetimeRange.model_validate(",2026-05-06")
+# SQL: WHERE field < '2026-05-06'
+```
+
+Each date part accepts ISO (`2026-04-01`, `2026-04-01T00:00:00Z`) and display format (`01.04.2026 00:00`).
+
+- `FilterDatetimeRange` — produces UTC-aware datetimes
+- `FilterNaiveDatetimeRange` — produces naive (timezone-unaware) datetimes
 
 ## Eager Loading
 
@@ -621,7 +648,8 @@ result = await soh.get_objects(session, User, order_by=order)
 
 ### Filter Types
 
-- `soh.FilterInt`, `soh.FilterStr`, `soh.FilterDate`, `soh.FilterDatetime`, `soh.FilterTimedelta`, `soh.FilterBool`, `soh.FilterExists`
+- `soh.FilterInt`, `soh.FilterStr`, `soh.FilterDate`, `soh.FilterDatetime`, `soh.FilterNaiveDatetime`, `soh.FilterTimedelta`, `soh.FilterBool`, `soh.FilterExists`
+- `soh.FilterDatetimeRange`, `soh.FilterNaiveDatetimeRange` -- Range filters that parse `"FROM,TO"` strings into `gt`/`lt` operators
 - `soh.OrderAsc`, `soh.OrderDesc`, `soh.OrderBy`
 - `soh.LogicalFilter`
 - `soh.TimeFilter` -- `created_after`, `created_before`, `updated_after`, `updated_before` with half-open interval `[after, before)`
@@ -634,7 +662,19 @@ result = await soh.get_objects(session, User, order_by=order)
 
 - `soh.Pagination` -- Request model (page, per\_page)
 - `soh.PaginationR` -- Response model (page, per\_page, total)
-- `soh.GetAllPagination[T]` -- Generic wrapper (data: list[T], pagination: PaginationR | None)
+- `soh.GetAllPagination[T]` -- Generic wrapper (table: TableMeta | None, columns: list[ColumnMeta] | None, data: list[T], pagination: PaginationR | None)
+
+### Table Metadata Types
+
+- `soh.TableMeta` -- Table-level metadata (name, header, row_link)
+- `soh.ColumnMeta` -- Column metadata (json_path, label, type, lookup_dict, lookup_path, bool_labels)
+- `soh.ColumnType` -- StrEnum of column data types (string, integer, float, boolean, date, datetime)
+- `soh.BoolLabels` -- Display labels for boolean columns (true_label, false_label)
+
+### Lookup Types
+
+- `soh.LookupMeta` -- Lookup metadata (name used as cache key, matches `ColumnMeta.lookup_dict`)
+- `soh.LookupResponse[T]` -- Generic wrapper for lookup endpoints (meta: LookupMeta, data: list[T])
 
 ### Projection Types
 
@@ -686,6 +726,19 @@ This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PAT
 - **MINOR** — new features (backwards compatible)
 - **MAJOR** — breaking changes
 
+## Changelog
+
+### 0.0.5
+
+- **FilterDatetimeRange** / **FilterNaiveDatetimeRange** — range filters that parse comma-separated date strings (`"2026-04-01,2026-05-06"`) into `gt`/`lt` operators for SQL filtering
+- **ColumnMeta** / **TableMeta** / **ColumnType** / **BoolLabels** — dynamic table metadata: backend describes columns, types, labels, lookups, and row navigation so the frontend renders any table without hardcoding
+- **GetAllPagination** — now includes optional `table` and `columns` fields for delivering table metadata alongside paginated data
+- **LookupMeta** / **LookupResponse** — standard `{meta, data}` wrapper for lookup (`_lkp`) endpoints, enabling unified frontend caching of dictionaries with `meta.name` as cache key
+
+### 0.0.4
+
+- Initial public release
+
 ## License
 
 This project is licensed under the **PolyForm Noncommercial License 1.0.0**.

{sqlmodel_object_helpers-0.0.4 → sqlmodel_object_helpers-0.0.5}/src/sqlmodel_object_helpers/__init__.py

@@ -1,6 +1,6 @@
 """sqlmodel-object-helpers — reusable query helpers for SQLModel projects."""
 
-__version__ = "0.0.4"
+__version__ = "0.0.5"
 
 from .constants import QueryHelperSettings, settings
 from .exceptions import (
@@ -30,9 +30,11 @@ from .types.filters import (
     FilterBool,
     FilterDate,
     FilterDatetime,
+    FilterDatetimeRange,
     FilterExists,
     FilterInt,
     FilterNaiveDatetime,
+    FilterNaiveDatetimeRange,
     FilterStr,
     FilterTimedelta,
     LogicalFilter,
@@ -41,8 +43,11 @@ from .types.filters import (
     OrderDesc,
     TimeFilter,
 )
+from .types.columns import BoolLabels, ColumnMeta, ColumnType, TableMeta
 from .types.pagination import (
     GetAllPagination,
+    LookupMeta,
+    LookupResponse,
     Pagination,
     PaginationR,
 )
@@ -57,7 +62,10 @@ __all__ = [
     "build_load_chain",
     "build_load_options",
     "check_for_related_records",
+    "BoolLabels",
+    "ColumnMeta",
     "ColumnSpec",
+    "ColumnType",
     "configure",
     "count_objects",
     "create_session_dependency",
@@ -68,9 +76,11 @@ __all__ = [
     "FilterBool",
     "FilterDate",
     "FilterDatetime",
+    "FilterDatetimeRange",
     "FilterExists",
     "FilterInt",
     "FilterNaiveDatetime",
+    "FilterNaiveDatetimeRange",
     "FilterStr",
     "FilterTimedelta",
     "flatten_filters",
@@ -81,6 +91,8 @@ __all__ = [
     "InvalidFilterError",
     "InvalidLoadPathError",
     "LogicalFilter",
+    "LookupMeta",
+    "LookupResponse",
     "MutationError",
     "ObjectNotFoundError",
     "Operator",
@@ -94,6 +106,7 @@ __all__ = [
     "settings",
     "SPECIAL_OPERATORS",
     "SUPPORTED_OPERATORS",
+    "TableMeta",
     "TimeFilter",
     "update_object",
     "update_objects",

sqlmodel_object_helpers-0.0.5/src/sqlmodel_object_helpers/types/__init__.py

@@ -0,0 +1,50 @@
+from .columns import BoolLabels, ColumnMeta, ColumnType, TableMeta
+from .datetime import UTCDatetime
+from .filters import (
+    FilterBool,
+    FilterDate,
+    FilterDatetime,
+    FilterDatetimeRange,
+    FilterExists,
+    FilterInt,
+    FilterNaiveDatetime,
+    FilterNaiveDatetimeRange,
+    FilterStr,
+    FilterTimedelta,
+    LogicalFilter,
+    OrderAsc,
+    OrderBy,
+    OrderDesc,
+    TimeFilter,
+)
+from .pagination import GetAllPagination, LookupMeta, LookupResponse, Pagination, PaginationR
+from .projections import ColumnSpec
+
+__all__ = [
+    "BoolLabels",
+    "ColumnMeta",
+    "ColumnSpec",
+    "ColumnType",
+    "FilterBool",
+    "FilterDate",
+    "FilterDatetime",
+    "FilterDatetimeRange",
+    "FilterExists",
+    "FilterInt",
+    "FilterNaiveDatetime",
+    "FilterNaiveDatetimeRange",
+    "FilterStr",
+    "FilterTimedelta",
+    "GetAllPagination",
+    "LogicalFilter",
+    "LookupMeta",
+    "LookupResponse",
+    "OrderAsc",
+    "OrderBy",
+    "OrderDesc",
+    "Pagination",
+    "PaginationR",
+    "TableMeta",
+    "TimeFilter",
+    "UTCDatetime",
+]

sqlmodel_object_helpers-0.0.5/src/sqlmodel_object_helpers/types/columns.py

@@ -0,0 +1,79 @@
+"""Column and table metadata for dynamic frontend table rendering."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ColumnType(StrEnum):
+    """Data type of a table column — determines how the frontend renders and filters it."""
+
+    STRING = "string"
+    INTEGER = "integer"
+    FLOAT = "float"
+    BOOLEAN = "boolean"
+    DATE = "date"
+    DATETIME = "datetime"
+
+
+class BoolLabels(BaseModel):
+    """Display labels for boolean columns.
+
+    Source: PostgreSQL domain comments, e.g.
+    ``COMMENT ON DOMAIN is_paid_domain IS 'Оплачено|Не оплачено'``
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    true_label: str
+    false_label: str
+
+
+class TableMeta(BaseModel):
+    """Table-level metadata.
+
+    Attributes:
+        name: Stable identifier used as a key for saving user settings
+            (e.g. ``"attempts"``).
+        header: Human-readable table title for the UI
+            (e.g. ``"Реестр попыток"``).
+        row_link: Optional URL template that makes each row clickable.
+            Uses ``$id`` as placeholder for the row identifier
+            (e.g. ``"/lead/$id"``, ``"/mail-template-lead/$id/edit"``).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    header: str
+    row_link: str | None = None
+
+
+class ColumnMeta(BaseModel):
+    """Metadata for a single table column sent to the frontend.
+
+    Attributes:
+        json_path: Dot-notation path to the value inside each ``data`` item
+            (e.g. ``"application.applicant.full_name"``).  Also serves as
+            the column identifier.
+        label: Human-readable column header (Russian name for the UI).
+        type: Data type — drives the filter widget and cell renderer on the
+            frontend.
+        lookup_dict: Optional name of the LKP dictionary the frontend
+            already has cached (e.g. ``"statuses"``).  When present the
+            frontend renders a ``<select>`` filter instead of free text.
+        lookup_path: Optional dot-notation path to the ID field used for
+            filtering when ``lookup_dict`` is set.  The frontend displays
+            ``json_path`` but sends ``lookup_path`` in filter requests.
+        bool_labels: Optional display labels for boolean values
+            (e.g. ``"Оплачено"`` / ``"Не оплачено"``).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    json_path: str
+    label: str
+    type: ColumnType = ColumnType.STRING
+    lookup_dict: str | None = None
+    lookup_path: str | None = None
+    bool_labels: BoolLabels | None = None

{sqlmodel_object_helpers-0.0.4 → sqlmodel_object_helpers-0.0.5}/src/sqlmodel_object_helpers/types/filters.py

@@ -1,4 +1,4 @@
-from datetime import date, datetime, timedelta
+from datetime import date, datetime, timedelta, timezone
 from typing import Any, Self
 
 from pydantic import BaseModel, ConfigDict, field_validator, model_validator
@@ -7,6 +7,38 @@ from ..constants import settings
 from .datetime import UTCDatetime
 
 
+def _parse_range_part(s: str) -> datetime:
+    """Parse a single date/datetime from a range string part.
+
+    Accepts ISO formats (``2026-04-01``, ``2026-04-01T00:00:00``,
+    ``2026-04-01T00:00:00.000Z``) and display format (``01.04.2026 00:00``).
+    """
+    s = s.strip()
+    if not s:
+        msg = "Empty date string"
+        raise ValueError(msg)
+
+    # ISO formats: 2026-04-01, 2026-04-01T00:00:00, 2026-04-01T00:00:00.000Z, +03:00 etc.
+    try:
+        normalized = s.removesuffix("Z") + "+00:00" if s.endswith("Z") else s
+        return datetime.fromisoformat(normalized)
+    except ValueError:
+        pass
+
+    # Display formats: DD.MM.YYYY, DD.MM.YYYY HH:MM, DD.MM.YYYY HH:MM:SS
+    for fmt in ("%d.%m.%Y %H:%M", "%d.%m.%Y %H:%M:%S", "%d.%m.%Y"):
+        try:
+            return datetime.strptime(s, fmt)  # noqa: DTZ007
+        except ValueError:
+            continue
+
+    msg = (
+        f"Invalid date format: {s!r}. "
+        "Expected YYYY-MM-DD, ISO datetime, or DD.MM.YYYY HH:MM"
+    )
+    raise ValueError(msg)
+
+
 class FilterInt(BaseModel):
     eq: int | None = None
     ne: int | None = None
@@ -97,6 +129,125 @@ class FilterTimedelta(BaseModel):
     le: timedelta | None = None
 
 
+def _split_range(range_str: str) -> tuple[str, str]:
+    """Split a range string by comma into (left, right) parts.
+
+    Returns stripped parts; either side may be empty for open-ended ranges.
+    """
+    if "," not in range_str:
+        msg = f"Invalid range format: {range_str!r}. Expected 'FROM,TO', 'FROM,', or ',TO'"
+        raise ValueError(msg)
+    left, right = range_str.split(",", maxsplit=1)
+    return left.strip(), right.strip()
+
+
+def _make_utc(dt: datetime) -> datetime:
+    """Ensure a datetime is UTC-aware. Naive datetimes are assumed UTC."""
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+class FilterDatetimeRange(BaseModel):
+    """
+    Range filter for datetime fields, parsed from a comma-separated string.
+
+    Supported string formats (separator is ``,``)::
+
+        "2026-04-01,2026-04-30"     — full range  (gt + lt)
+        "2026-04-01,"               — from date   (gt only, open end)
+        ",2026-04-30"               — to date     (lt only, open start)
+
+    Each date part accepts ISO (``2026-04-01``, ``2026-04-01T00:00:00Z``)
+    and display format (``01.04.2026 00:00``).
+
+    After validation the model contains UTC-aware ``gt`` and/or ``lt`` fields
+    that map directly to SQLAlchemy operators via ``model_dump(exclude_none=True)``.
+    """
+
+    gt: UTCDatetime | None = None
+    lt: UTCDatetime | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def parse_range_string(cls, data: Any) -> Any:
+        if isinstance(data, str):
+            return cls._parse_range(data)
+        return data
+
+    @staticmethod
+    def _parse_range(range_str: str) -> dict[str, datetime]:
+        range_str = range_str.strip()
+        if not range_str:
+            msg = "Range string must not be empty"
+            raise ValueError(msg)
+
+        left, right = _split_range(range_str)
+        result: dict[str, datetime] = {}
+
+        if left:
+            result["gt"] = _make_utc(_parse_range_part(left))
+        if right:
+            result["lt"] = _make_utc(_parse_range_part(right))
+
+        return result
+
+    @model_validator(mode="after")
+    def validate_range(self) -> Self:
+        if self.gt is None and self.lt is None:
+            msg = "At least one of gt or lt must be set"
+            raise ValueError(msg)
+        if self.gt is not None and self.lt is not None and self.gt > self.lt:
+            msg = "Range start (gt) must not be after range end (lt)"
+            raise ValueError(msg)
+        return self
+
+
+class FilterNaiveDatetimeRange(BaseModel):
+    """
+    Same as :class:`FilterDatetimeRange` but produces **naive** (timezone-unaware) datetimes.
+
+    If the input contains timezone info, it is stripped (replaced with None).
+    """
+
+    gt: datetime | None = None
+    lt: datetime | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def parse_range_string(cls, data: Any) -> Any:
+        if isinstance(data, str):
+            return cls._parse_range(data)
+        return data
+
+    @staticmethod
+    def _parse_range(range_str: str) -> dict[str, datetime]:
+        range_str = range_str.strip()
+        if not range_str:
+            msg = "Range string must not be empty"
+            raise ValueError(msg)
+
+        left, right = _split_range(range_str)
+        result: dict[str, datetime] = {}
+
+        if left:
+            result["gt"] = _parse_range_part(left).replace(tzinfo=None)
+        if right:
+            result["lt"] = _parse_range_part(right).replace(tzinfo=None)
+
+        return result
+
+    @model_validator(mode="after")
+    def validate_range(self) -> Self:
+        if self.gt is None and self.lt is None:
+            msg = "At least one of gt or lt must be set"
+            raise ValueError(msg)
+        if self.gt is not None and self.lt is not None and self.gt > self.lt:
+            msg = "Range start (gt) must not be after range end (lt)"
+            raise ValueError(msg)
+        return self
+
+
 class FilterBool(BaseModel):
     eq: bool | None = None
     ne: bool | None = None

sqlmodel_object_helpers-0.0.5/src/sqlmodel_object_helpers/types/pagination.py

@@ -0,0 +1,49 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+from .columns import ColumnMeta, TableMeta
+
+
+class Pagination(BaseModel):
+    page: int | None = Field(default=1, ge=1)
+    per_page: int | None = Field(default=10, ge=1)
+
+
+class PaginationR(Pagination):
+    total: int
+
+
+class GetAllPagination[T](BaseModel):
+    table: TableMeta | None = None
+    columns: list[ColumnMeta] | None = None
+    data: list[T]
+    pagination: PaginationR | None = None
+
+
+class LookupMeta(BaseModel):
+    """Metadata for a lookup dictionary response.
+
+    Attributes:
+        name: Stable identifier used as the cache key on the frontend
+            (e.g. ``"lead_email_types"``). Must match
+            ``ColumnMeta.lookup_dict`` values.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+
+
+class LookupResponse[T](BaseModel):
+    """Standard response wrapper for lookup (``_lkp``) endpoints.
+
+    Mirrors the ``{meta, data}`` pattern the frontend uses for caching::
+
+        store.lookups["lead_email_types"] = {meta: {name: "lead_email_types"}, data: [...]}
+
+    Attributes:
+        meta: Lookup metadata (name used as cache key).
+        data: List of lookup records.
+    """
+
+    meta: LookupMeta
+    data: list[T]