easyvista-python-client 0.1.0__py3-none-any.whl

easyvista_python_client/models/department.py

@@ -0,0 +1,68 @@
+"""Models for the EasyVista ``departments`` resource.
+
+``Department`` declares the stable scalar fields; ``extra="allow"`` (from
+``EasyvistaModel``) preserves the localized ``DEPARTMENT_<lang>`` label columns (used
+by ``name``), the ``COMMENT_DEPARTMENT`` Memo link (surfaced by
+``classify_fields().links`` and read via ``client.get_department_comment``), and any
+instance-specific columns. Field aliases are grounded in the live inventory
+(``docs/easyvista-field-inventory.md``). Writes are **provisional** pending an
+authorised profile (spec open item O-DIR-2).
+"""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from ..references import localized_label
+from .common import EasyvistaModel, EasyvistaWriteModel, OptionalInt
+
+
+class Department(EasyvistaModel):
+    """A department (organisation node) as returned by the API."""
+
+    department_id: OptionalInt = Field(default=None, alias="DEPARTMENT_ID")
+    department_code: str | None = Field(default=None, alias="DEPARTMENT_CODE")
+    department_path: str | None = Field(default=None, alias="DEPARTMENT_PATH")
+    manager_id: OptionalInt = Field(default=None, alias="MANAGER_ID")
+    level: OptionalInt = Field(default=None, alias="LEVEL")
+    href: str | None = Field(default=None, alias="HREF")
+
+    @property
+    def name(self) -> str | None:
+        """Best localized department label, falling back to code then path.
+
+        A plain property (not a serialized field), so it never recurses through
+        ``model_dump`` or appears in ``classify_fields``.
+        """
+        return localized_label(
+            self.model_dump(by_alias=True),
+            "DEPARTMENT",
+            fallbacks=(self.department_code, self.department_path),
+        )
+
+
+class PostDepartment(EasyvistaWriteModel):
+    """Provisional payload for creating a department.
+
+    Sent inside the envelope ``{"departments": [...]}``. Field set is a best guess
+    pending an authorised profile (spec open item O-DIR-2);
+    ``custom_fields`` serialize with an ``e_`` prefix (see ``EasyvistaWriteModel``).
+    """
+
+    department_code: str | None = None
+    department_en: str | None = None
+    department_fr: str | None = None
+    manager_id: int | None = None
+    parent_department_id: int | None = None
+
+
+class DepartmentUpdate(EasyvistaWriteModel):
+    """Provisional payload for updating a department via PUT.
+
+    Field set pending an authorised profile (spec open item O-DIR-2).
+    """
+
+    department_code: str | None = None
+    department_en: str | None = None
+    department_fr: str | None = None
+    manager_id: int | None = None

easyvista_python_client/models/document.py

@@ -0,0 +1,32 @@
+"""Model for documents attached to an EasyVista ticket."""
+
+from __future__ import annotations
+
+from pydantic import Field, model_validator
+
+from .common import EasyvistaModel
+
+
+class Document(EasyvistaModel):
+    """A document attached to a ticket (or the HREF returned after upload).
+
+    The live ``GET requests/{rfc}/documents`` list exposes each attachment as
+    ``DOCUMENT`` (filename), ``DOCUMENT_ID`` and ``DDL_HREF`` (the direct-download
+    URL) — verified against a live instance. ``filename`` falls back to
+    ``DOCUMENT`` (then ``NAME``) so it is populated on both the list shape and any
+    ``FILE_NAME``-style shape; ``download_href`` is the URL to fetch the bytes.
+    """
+
+    href: str | None = Field(default=None, alias="HREF")
+    filename: str | None = Field(default=None, alias="FILE_NAME")
+    name: str | None = Field(default=None, alias="NAME")
+    document: str | None = Field(default=None, alias="DOCUMENT")
+    document_id: str | None = Field(default=None, alias="DOCUMENT_ID")
+    download_href: str | None = Field(default=None, alias="DDL_HREF")
+
+    @model_validator(mode="after")
+    def _fill_filename(self) -> Document:
+        """Populate ``filename`` from ``DOCUMENT`` or ``NAME`` when unset."""
+        if not self.filename:
+            self.filename = self.document or self.name
+        return self

easyvista_python_client/models/employee.py

@@ -0,0 +1,67 @@
+"""Models for the EasyVista ``employees`` resource.
+
+``Employee`` declares the fields the richer single-record GET returns
+(``GET employees/{id}``). ``E_MAIL`` is a **declared official** field, so the generic
+field model never misclassifies it as a custom ``e_*`` column. ``extra="allow"``
+preserves the ``COMMENT_EMPLOYEE`` Memo link and any other columns. Aliases are
+grounded in the live inventory (``docs/easyvista-field-inventory.md``). Writes are
+**provisional** pending an authorised profile (spec open item O-DIR-2).
+"""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from .common import EasyvistaModel, EasyvistaWriteModel, OptionalInt
+
+
+class Employee(EasyvistaModel):
+    """An employee (person) as returned by the single-record GET."""
+
+    employee_id: OptionalInt = Field(default=None, alias="EMPLOYEE_ID")
+    last_name: str | None = Field(default=None, alias="LAST_NAME")
+    e_mail: str | None = Field(default=None, alias="E_MAIL")
+    department_id: OptionalInt = Field(default=None, alias="DEPARTMENT_ID")
+    department_path: str | None = Field(default=None, alias="DEPARTMENT_PATH")
+    location_id: OptionalInt = Field(default=None, alias="LOCATION_ID")
+    phone_number: str | None = Field(default=None, alias="PHONE_NUMBER")
+    cellular_number: str | None = Field(default=None, alias="CELLULAR_NUMBER")
+    profil_id: OptionalInt = Field(default=None, alias="PROFIL_ID")
+    manager_id: OptionalInt = Field(default=None, alias="MANAGER_ID")
+    employee_guid: str | None = Field(default=None, alias="EMPLOYEE_GUID")
+    identification: str | None = Field(default=None, alias="IDENTIFICATION")
+    login: str | None = Field(default=None, alias="LOGIN")
+    function_id: OptionalInt = Field(default=None, alias="FUNCTION_ID")
+    language_id: OptionalInt = Field(default=None, alias="LANGUAGE_ID")
+    last_update: str | None = Field(default=None, alias="LAST_UPDATE")
+    href: str | None = Field(default=None, alias="HREF")
+
+
+class PostEmployee(EasyvistaWriteModel):
+    """Provisional payload for creating an employee (envelope ``{"employees": [...]}``).
+
+    Field set is a best guess pending an authorised profile (spec open item O-DIR-2);
+    ``custom_fields`` serialize with an ``e_`` prefix (see ``EasyvistaWriteModel``).
+    """
+
+    last_name: str | None = None
+    e_mail: str | None = None
+    department_id: int | None = None
+    location_id: int | None = None
+    phone_number: str | None = None
+    cellular_number: str | None = None
+    manager_id: int | None = None
+    login: str | None = None
+    function_id: int | None = None
+
+
+class EmployeeUpdate(EasyvistaWriteModel):
+    """Provisional payload for updating an employee via PUT (spec open item O-DIR-2)."""
+
+    last_name: str | None = None
+    e_mail: str | None = None
+    department_id: int | None = None
+    location_id: int | None = None
+    phone_number: str | None = None
+    cellular_number: str | None = None
+    manager_id: int | None = None

easyvista_python_client/models/request.py

@@ -0,0 +1,172 @@
+"""Models for the EasyVista ``requests`` resource (tickets).
+
+``Request``'s declared fields are those verified present on live single-ticket
+GETs (see its class docstring for exactly which, and which are deliberately
+left undeclared); ``extra="allow"`` preserves everything else. ``PostRequest``
+and ``RequestUpdate`` field sets follow the documented create/update bodies
+(see their own docstrings).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field, model_validator
+
+from .common import EasyvistaModel, EasyvistaWriteModel, OptionalInt
+
+
+class Request(EasyvistaModel):
+    """A ticket (incident/request) as returned by the API.
+
+    The declared fields are those verified present on live single-ticket GETs.
+    ``extra="allow"`` preserves everything else, including the deliberately
+    undeclared ones:
+
+    * ``*_PATH`` (``SD_CATALOG_PATH``, ``DEPARTMENT_PATH``) — verified live:
+      returned and populated, but **silently ignored as search conditions** (a
+      real value returns the whole table while its ``*_ID`` sibling filters).
+      ``LOCATION_PATH`` is *presumed* to behave the same by family resemblance
+      only — no sampled ticket carried both ``LOCATION_PATH`` and
+      ``LOCATION_ID``, so it was never actually tested. Left undeclared so this
+      model never invites filtering on any of them.
+    * ``E_*`` — instance-specific custom fields; they belong in the custom
+      bucket of :meth:`~EasyvistaModel.classify_fields`, not here.
+    * ``AVAILABLE_FIELD_*`` — the API's spare slots.
+
+    ``TITLE`` is empty on tickets created through the portal/catalog on some
+    instances (the human summary lives in ``DESCRIPTION`` / the catalog path),
+    so ``title`` is legitimately ``None`` for those; it is populated for tickets
+    created through this client with ``PostRequest(title=...)``.
+    """
+
+    # identity
+    rfc_number: str | None = Field(default=None, alias="RFC_NUMBER")
+    request_id: OptionalInt = Field(default=None, alias="REQUEST_ID")
+    href: str | None = Field(default=None, alias="HREF")
+
+    # content
+    title: str | None = Field(default=None, alias="TITLE")
+    # The list view returns DESCRIPTION inline (a string); the single-ticket GET
+    # expands it into an HREF reference object (``{"HREF": ".../description"}``).
+    # Accept either so both read paths validate. Whether the resolved text is
+    # HTML or plain text is still unverified (spec open item O4).
+    description: str | dict[str, Any] | None = Field(default=None, alias="DESCRIPTION")
+    external_reference: str | None = Field(default=None, alias="EXTERNAL_REFERENCE")
+
+    # classification
+    sd_catalog_id: OptionalInt = Field(default=None, alias="SD_CATALOG_ID")
+    status_id: OptionalInt = Field(default=None, alias="STATUS_ID")
+    urgency_id: OptionalInt = Field(default=None, alias="URGENCY_ID")
+    impact_id: OptionalInt = Field(default=None, alias="IMPACT_ID")
+    severity_id: OptionalInt = Field(default=None, alias="SEVERITY_ID")
+    # Write-side ``PostRequest.origin`` reads back as REQUEST_ORIGIN_ID; ``ORIGIN``
+    # itself is not returned (spec open item O-ORIGIN).
+    request_origin_id: OptionalInt = Field(default=None, alias="REQUEST_ORIGIN_ID")
+
+    # parties and place
+    department_id: OptionalInt = Field(default=None, alias="DEPARTMENT_ID")
+    location_id: OptionalInt = Field(default=None, alias="LOCATION_ID")
+    requestor_id: OptionalInt = Field(default=None, alias="REQUESTOR_ID")
+    recipient_id: OptionalInt = Field(default=None, alias="RECIPIENT_ID")
+    owner_id: OptionalInt = Field(default=None, alias="OWNER_ID")
+
+    # timestamps and time limits — verified *returned*; their accepted write
+    # format is NOT verified (both a string and an int probe return HTTP 590),
+    # so no datetime parsing is claimed here. See spec open item O-590-DATE.
+    #
+    # These are the OFFICIAL time fields, portable across EasyVista
+    # deployments. The instance-specific GTR/GTI family (``E_GTR_STATUS``,
+    # ``E_GTI_UT``, ``E_DELAI_PEC``…) is deliberately NOT declared: it does not
+    # exist on another deployment, so it belongs in the custom bucket of
+    # :meth:`classify_fields`, reached by name at the call site.
+    submit_date_ut: str | None = Field(default=None, alias="SUBMIT_DATE_UT")
+    creation_date_ut: str | None = Field(default=None, alias="CREATION_DATE_UT")
+    max_resolution_date_ut: str | None = Field(
+        default=None, alias="MAX_RESOLUTION_DATE_UT"
+    )
+    expected_date_ut: str | None = Field(default=None, alias="EXPECTED_DATE_UT")
+    end_date_ut: str | None = Field(default=None, alias="END_DATE_UT")
+    last_update: str | None = Field(default=None, alias="LAST_UPDATE")
+    sla_id: OptionalInt = Field(default=None, alias="SLA_ID")
+    # Verified live (2026-07-28 Phase 0 probe, U6) as a string on every ticket
+    # checked -- never an int -- so no int branch is declared here.
+    time_used_to_solve_request: str | None = Field(
+        default=None, alias="TIME_USED_TO_SOLVE_REQUEST"
+    )
+
+    @model_validator(mode="after")
+    def _derive_rfc_from_href(self) -> Request:
+        """Populate ``rfc_number`` from ``href`` when the API omits it.
+
+        ``POST /requests`` (create) returns an HREF-only body
+        ``{"HREF": ".../requests/<id>"}`` with no ``RFC_NUMBER``; the trailing
+        path segment of that HREF *is* the ticket's RFC (verified live), so
+        callers can use ``ticket.rfc_number`` immediately after a create. Reads,
+        which already carry ``RFC_NUMBER``, are left untouched.
+        """
+        if not self.rfc_number and isinstance(self.href, str) and self.href:
+            tail = self.href.rstrip("/").rsplit("/", 1)[-1].split("?", 1)[0]
+            if tail:
+                self.rfc_number = tail
+        return self
+
+
+class PostRequest(EasyvistaWriteModel):
+    """Payload for creating a ticket.
+
+    Field set matches the documented create body (``docs/API_Info.md``),
+    verified against a live instance: a ticket needs at minimum ``catalog_code``
+    plus ``title`` (and typically ``origin`` / ``department_id``). The exact
+    mandatory fields are configured **per catalog on the EasyVista side**, so the
+    client cannot know them statically; a missing one is rejected server-side and
+    surfaces as :class:`EasyvistaValidationError` (HTTP 590, code 2013), not a
+    retried server error. ``custom_fields`` values are serialized with an ``e_``
+    prefix unless they already start with ``e_`` (see :class:`EasyvistaWriteModel`).
+
+    ``catalog_code`` is the only verified way to name a catalog here. An earlier
+    ``catalog_guid`` field was removed: it is absent from the documented create
+    body, and it cannot be verified on a profile where ``GET /catalog-requests``
+    returns 403 (no way to obtain a real catalog GUID).
+
+    ``description`` supplied at create time was **not** readable back through
+    either Memo on the verified instance -- neither ``DESCRIPTION`` nor
+    ``COMMENT``. To set body text you can read again, follow the create with
+    ``update_ticket(rfc, RequestUpdate(description=...))``.
+    """
+
+    catalog_code: str | None = None
+    title: str | None = None
+    description: str | None = None
+    origin: int | None = None
+    department_id: int | None = None
+    urgency_id: int | None = None
+    impact_id: int | None = None
+    severity_id: int | None = None
+    recipient_id: int | None = None
+    recipient_mail: str | None = None
+    external_reference: str | None = None
+
+
+class RequestUpdate(EasyvistaWriteModel):
+    """Payload for updating a ticket via PUT.
+
+    ``docs/API_Info.md`` documents only the create, comment and close bodies, so
+    the update body is not vendor-documented. Every field here is one verified
+    accepted against a live instance -- ``title`` by the Phase 0 probe and by
+    ``integration_tests/test_live_ticket_identity.py``. Nothing is added
+    speculatively: an unaccepted field would silently no-op or raise HTTP 590.
+
+    ``description`` writes the ticket's **COMMENT** Memo, not ``DESCRIPTION`` --
+    verified live. EasyVista models ``COMMENT`` as the request's justification
+    and ``DESCRIPTION`` as a separate Memo; which one a deployment actually
+    populates is a per-instance configuration choice. On the instance this
+    client was verified against, ``DESCRIPTION`` is empty on every ticket and
+    ``COMMENT`` carries the body text. Read it back with
+    ``resolve_memo("requests/{rfc}/comment")``, or take
+    ``TicketContext.comment``, which resolves it for you.
+    """
+
+    status_id: int | None = None
+    title: str | None = None
+    description: str | None = None

easyvista_python_client/pagination.py

@@ -0,0 +1,84 @@
+"""Search-result container and record extraction for list endpoints."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class SearchResult(Generic[T]):
+    """A page of search results plus EasyVista's record counts.
+
+    ``next_url`` is the API's ``@next`` link (an ``offset``-based next-page URL)
+    when more records exist than were returned, else ``None``. It is the
+    authoritative "are there more pages?" signal used by the iterators.
+    """
+
+    records: list[T]
+    record_count: int
+    total_record_count: int
+    href: str | None = None
+    next_url: str | None = None
+
+
+def _to_int(value: Any, default: int) -> int:
+    """Coerce an EasyVista count to ``int``, falling back to ``default``."""
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def build_search_result(data: Any, records: list[T]) -> SearchResult[T]:
+    """Assemble a :class:`SearchResult` from a payload and its typed records.
+
+    The live API returns ``record_count`` / ``total_record_count`` as **strings**
+    (spec open item O1), so they are coerced to ``int`` here — the single place
+    both the ``requests`` and ``assets`` search parsers funnel through.
+    """
+    if not isinstance(data, dict):
+        return SearchResult(
+            records=records,
+            record_count=len(records),
+            total_record_count=len(records),
+        )
+    count = _to_int(data.get("record_count"), len(records))
+    total = _to_int(data.get("total_record_count"), count)
+    href = data.get("HREF")
+    next_url = data.get("@next")
+    return SearchResult(
+        records=records,
+        record_count=count,
+        total_record_count=total,
+        href=href if isinstance(href, str) else None,
+        next_url=next_url if isinstance(next_url, str) else None,
+    )
+
+
+def extract_records(data: Any, envelope_key: str | None = None) -> list[dict[str, Any]]:
+    """Pull a list of record dicts out of an EasyVista JSON payload.
+
+    Handles the ``records`` list (GET list), the resource-named create/list
+    envelopes, and a bare single object. ``envelope_key`` names a resource's own
+    envelope (e.g. ``"departments"``) so a response echoed in that wrapper is
+    unwrapped too; it is checked right after ``records`` and before the legacy
+    defaults. With ``envelope_key=None`` the behavior is unchanged.
+    """
+    if isinstance(data, dict):
+        keys = ["records"]
+        if envelope_key and envelope_key not in keys:
+            keys.append(envelope_key)
+        keys.extend(k for k in ("requests", "assets", "documents") if k not in keys)
+        for key in keys:
+            value = data.get(key)
+            if isinstance(value, list):
+                return [r for r in value if isinstance(r, dict)]
+        return [data]
+    if isinstance(data, list):
+        return [r for r in data if isinstance(r, dict)]
+    return []

easyvista_python_client/references.py

@@ -0,0 +1,146 @@
+"""Generic, config-free resolution of EasyVista reference attributes.
+
+EasyVista returns reference attributes in two shapes: nested objects that carry a
+human label in ``*_EN`` / ``*_FR`` / ``*_PATH`` sub-keys (e.g. ``STATUS``,
+``DEPARTMENT``, ``CATALOG_REQUEST``), and bare ids (e.g. ``URGENCY_ID``). This
+module normalizes both to a :class:`Reference` using only the API's naming
+conventions, so any field — including custom ``e_*`` fields on any instance —
+resolves the same way with no registry or configuration.
+
+Leaf module: stdlib only, no model/client imports.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Reference:
+    """A normalized EasyVista reference: an id and/or a human label."""
+
+    id: str | None
+    label: str | None
+
+    @property
+    def display(self) -> str | None:
+        """The human label when available, else the id, else ``None``."""
+        return self.label or self.id
+
+
+def _scalar(value: Any) -> str | None:
+    """A non-empty id-like scalar as a string, else ``None`` (bools rejected)."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (str, int)) and str(value).strip():
+        return str(value).strip()
+    return None
+
+
+def _nested_label(nested: dict[str, Any] | None) -> str | None:
+    """First non-empty ``*_EN`` then ``*_FR`` then ``*_PATH`` string; never an href."""
+    if not nested:
+        return None
+    # Suffix-scan (not <name>_* prefix) so labels under any sub-key resolve —
+    # e.g. CATALOG_REQUEST's human label lives in TITLE_FR / TITLE_EN.
+    for suffix in ("_EN", "_FR", "_PATH"):
+        for key, value in nested.items():
+            if (
+                key.upper().endswith(suffix)
+                and isinstance(value, str)
+                and value.strip()
+            ):
+                return value.strip()
+    return None
+
+
+def resolve_reference(record: dict[str, Any], name: str) -> Reference:
+    """Resolve reference ``name`` in a model's by-alias dump to ``(id, label)``.
+
+    ``name`` is a raw API field name, matched case-insensitively. See the module
+    docstring for the conventions. Never raises; a non-dict record or a missing
+    field yields an empty :class:`Reference`.
+    """
+    if not isinstance(record, dict):
+        return Reference(id=None, label=None)
+    # Index top-level keys case-insensitively (EasyVista keys are ALL_CAPS, but
+    # custom fields on some instances are not — stay generic).
+    upper = {k.upper(): v for k, v in record.items() if isinstance(k, str)}
+    key = name.upper()
+
+    value = upper.get(key)
+    nested = value if isinstance(value, dict) else None
+
+    label = _nested_label(nested)
+    id_ = _resolve_id(upper, key, nested)
+    return Reference(id=id_, label=label)
+
+
+def _resolve_id(
+    upper: dict[str, Any], key: str, nested: dict[str, Any] | None
+) -> str | None:
+    # 1. top-level <name>_ID / <name>_GUID / the scalar at <name> itself
+    for candidate in (f"{key}_ID", f"{key}_GUID", key):
+        got = _scalar(upper.get(candidate))
+        if got is not None:
+            return got
+    if nested:
+        # 2. exact <name>_ID / <name>_GUID inside the nested object
+        for sub in (f"{key}_ID", f"{key}_GUID"):
+            for nkey, nval in nested.items():
+                if isinstance(nkey, str) and nkey.upper() == sub:
+                    got = _scalar(nval)
+                    if got is not None:
+                        return got
+        # Best-effort: first *_ID/_GUID sub-key by dict order (fine for the
+        # single-id nested objects EasyVista returns).
+        for nkey, nval in nested.items():
+            if isinstance(nkey, str) and nkey.upper().endswith(("_ID", "_GUID")):
+                got = _scalar(nval)
+                if got is not None:
+                    return got
+    return None
+
+
+_LANG_SUFFIXES = ("_EN", "_FR", "_GE", "_IT", "_PO", "_SP")
+
+
+def _usable_label(value: Any) -> str | None:
+    """A stripped non-empty string that is not a ``[bracketed]`` placeholder.
+
+    Returns ``None`` otherwise.
+    """
+    if not isinstance(value, str):
+        return None
+    text = value.strip()
+    if not text or (text.startswith("[") and text.endswith("]")):
+        return None
+    return text
+
+
+def localized_label(
+    record: dict[str, Any], prefix: str, *, fallbacks: tuple[str | None, ...] = ()
+) -> str | None:
+    """Best populated ``"<prefix>_<lang>"`` label, else first usable ``fallbacks``.
+
+    Scans the EasyVista language columns ``<prefix>_EN`` → ``_FR`` → ``_GE`` → ``_IT``
+    → ``_PO`` → ``_SP`` and returns the first value that is a non-empty string and not
+    a ``[bracketed]`` placeholder (unpopulated localized columns on a single-language
+    instance echo ``"[CODE]"``). Only the language suffixes are considered, so
+    ``_CODE`` / ``_PATH`` are never mistaken for a label. Falls back to the first
+    usable value in ``fallbacks`` (e.g. a code then a path). Case-insensitive on keys;
+    never raises; returns ``None`` when nothing usable is found.
+    """
+    if isinstance(record, dict):
+        upper = {k.upper(): v for k, v in record.items() if isinstance(k, str)}
+        base = prefix.upper()
+        for suffix in _LANG_SUFFIXES:
+            got = _usable_label(upper.get(base + suffix))
+            if got is not None:
+                return got
+    for value in fallbacks:
+        got = _usable_label(value)
+        if got is not None:
+            return got
+    return None