easyvista-python-client 0.2.0__tar.gz → 0.3.0__tar.gz

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/CHANGELOG.md

@@ -4,11 +4,124 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-While the package is pre-1.0, breaking changes may land between minor versions;
-a deprecation policy will follow the 1.0 release.
+While the package is pre-1.0, breaking changes may land between **minor**
+versions; a deprecation policy will follow the 1.0 release. A patch release
+never carries one. Each breaking change is marked `**BREAKING**` in its section
+with the reasoning, so read the section for the version you are moving to.
+
+**The git tag is what defines a version.** Where a section's narrative or date
+disagrees with the tree its tag points at, the tag is authoritative and the prose
+is the error. Tags carry no `v` prefix.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-02
+
+Makes the task-vs-action distinction inspectable. A GLPI comment corresponds to
+an EasyVista **task**, not an action; actions carry effort and cost, so a
+timeline mirrored without that distinction imports time-tracking and workflow
+rows as conversation.
+
+**Upgrading.** One breaking change, in `Action` (see `### Changed`). The minor
+bump is deliberate: a dependant pinned `>=0.2.0,<0.3` does **not** pick this up,
+and must widen its constraint on purpose — which is the point, because the
+retyping below can change an answer silently rather than raise.
+
+Before widening, check whether you read `action.ELAPSED_TIME`, `TIME_COST`,
+`CONTRACTUAL_COST`, `START_DATE_UT` or `END_DATE_UT` off `model_extra`, or read
+those keys out of a `model_dump(by_alias=True)` and treated them as strings. Both
+change here. Nothing on the write side moves: `PostAction`, `PostTask` and
+`ActionUpdate` are untouched.
+
+### Added
+
+- Five columns declared on `Action` with real types: `elapsed_time` (minutes,
+  `int | None`), `time_cost` and `contractual_cost` (exact `Decimal | None`,
+  parsed from the API's French decimal comma), `start_date_ut` and
+  `end_date_ut` (aware `datetime | None`). They previously arrived only as
+  untyped `extra="allow"` strings.
+
+  **The `""` sentinel and `"0"` stay different answers.** `""` means the column
+  does not apply to this record and maps to `None`; `"0"` / `"0,00"` means it
+  applies and is zero, and maps to `0` / `Decimal("0.00")`. Collapsing the two
+  destroys the only signal that says whether a record tracks effort. Measured
+  over 1500 live rows: `ELAPSED_TIME` was `""` on 384 and `"0"` on 895.
+- `Action.is_workflow_generated` — whether `WORKFLOW_ID` is set, i.e. whether
+  the workflow engine owns the row. Clean on 1500/1500 measured rows, and the
+  one structural fact in this area that holds.
+
+  It is **not** an `is_task()`, and the package deliberately does not ship one:
+  nothing on an action record says which route created it, and the
+  effort-shape heuristic that looks like it should is wrong in both directions
+  — 173 of 1500 rows had a `WORKFLOW_ID` with an empty `ELAPSED_TIME`, and 39
+  of 49 public comments carried a non-empty one, one of them with a real
+  `TIME_COST` of `99,00`. Which action types count as conversation is
+  per-deployment policy and stays with the caller.
+- `scripts/tests/test_no_private_instance_identifiers.py` — a guard refusing any
+  private EasyVista instance identifier (hostname, domain, real catalog GUID or
+  code) in a tracked file. `.gitignore` has always stated that policy in prose;
+  it had no enforcement, and preparing this release put a real preprod hostname
+  into `docs/vendor-api-reference.md` — a tracked file that also ships in the
+  sdist — with all five gates passing, because none of them reads prose for
+  this. Both a public push and a PyPI upload are irreversible, so the check is
+  now mechanical. It carries its own negative control, and deliberately does
+  **not** refuse the illustrative account number or the synthetic
+  `EAZ_INC_000` stand-in the tracked tests already use.
+- `models.common.OptionalDecimal`, the annotated type behind the two cost
+  columns. Accepts either decimal separator, so a dot-configured deployment
+  needs no setting, and **refuses a grouping separator** rather than guessing
+  — `'1.234,56'` and `'1,234.56'` are the same amount under opposite
+  conventions. Not exported from the package root.
+
+### Changed
+
+- **BREAKING** — `ELAPSED_TIME`, `TIME_COST`, `CONTRACTUAL_COST`,
+  `START_DATE_UT` and `END_DATE_UT` are now declared fields on `Action` instead
+  of `extra="allow"` extras. Three consequences:
+  - `action.ELAPSED_TIME` (extra attribute access) raises `AttributeError`; use
+    `action.elapsed_time`. The same for the other four.
+  - They are gone from `action.model_extra`, and
+    `model_dump(by_alias=True)["ELAPSED_TIME"]` is now an `int | None` rather
+    than a `str`.
+  - `classify_fields()` bucketing is **unchanged** — none of the five starts
+    with `E_`, so all five have always landed in `.official`. What changed is
+    *presence*: `.official` (and the dump) now always carries all five keys,
+    `None` included, where previously a key the API did not return was simply
+    absent. Code that iterates `.official` sees five more keys on a default
+    `list_actions` row.
+  - **`None` is now ambiguous.** These columns are not on the default
+    `list_actions` projection, so on a default row every one reads `None`,
+    meaning *not returned* — not the `""` that means *does not apply*. The two
+    are indistinguishable once validated. Project them explicitly or read
+    item-level before reading meaning into a `None`.
+  - A `Decimal` in a dump is not JSON-serialisable, so
+    `json.dumps(action.model_dump(by_alias=True))` raises where a cost is
+    populated. Use `model_dump(mode="json")`, which renders the amount as a
+    string with a `.` decimal point rather than the `,` the API sent.
+  - A malformed value now raises where it previously passed through as a
+    string. This is the same trade `OptionalDateTime` already makes — a wrong
+    number is worse than a loud failure — and it carries the same blast radius:
+    the descriptor validates a page in a list comprehension, so one bad value
+    fails a whole `list_actions` call. See `O-COSTGROUP` in
+    `docs/vendor-api-reference.md`.
+
+### Documentation
+
+- `docs/vendor-api-reference.md` records, as tier 2 read on two 2025.3
+  deployments on 2026-09-02, that `/requests/{rfc_number}/tasks` is **POST
+  only** and that **no task read route exists** under any spelling — the only
+  timeline reads are `GET /actions`, `/actions/{id}` and
+  `/actions/{id}/{comment}`. A task is written as a task and read back as an
+  action, which is why there is no `list_tasks`/`iter_tasks` and why
+  `create_task` returns an `Action`. `create_task`'s docstring now says so
+  where a reader meets it.
+- Same file, tier 4: the effort-column measurements above, and two side
+  findings. `ACTION_LABEL_*` is the label of the workflow **step**, not the
+  name of the action type — type 20 appeared under six different labels — so
+  it is a stable type name only for the non-workflow types. And types 14, 27
+  and 28 have an empty label in every language column at both list and item
+  level, so those ids cannot be named through the API at all (`O-ACTIONTYPE28`).
+
 ## [0.2.0] - 2026-09-02
 
 The first release since `0.1.0`. A `0.2.0` section was prepared and dated
@@ -1002,6 +1115,13 @@ the release is additive.
 
 Initial public release.
 
+> **The tag is authoritative, and it disagrees with this date.** The `0.1.0` tag
+> points at `3216a33` (2026-08-04), roughly 150 commits after `6df6a75`, the
+> commit this section was written to describe. Per the policy above, `0.1.0`
+> **is** the tree at `3216a33`; the date on this heading and the scope below
+> under-describe it. The tag is published, so it is not being moved — this note
+> exists so the discrepancy is recorded rather than rediscovered.
+
 ### Added
 
 - Synchronous `EasyvistaClient` and asynchronous `AsyncEasyvistaClient` over the
@@ -1022,6 +1142,7 @@ Initial public release.
   status/error code, with non-retryable validation errors (HTTP 590, code 2013).
 - `py.typed` marker — the package ships inline type information.
 
-[Unreleased]: https://github.com/baraline/easyvista_python_client/compare/v0.2.0...HEAD
-[0.2.0]: https://github.com/baraline/easyvista_python_client/compare/0.1.0...v0.2.0
+[Unreleased]: https://github.com/baraline/easyvista_python_client/compare/0.3.0...HEAD
+[0.3.0]: https://github.com/baraline/easyvista_python_client/compare/0.2.0...0.3.0
+[0.2.0]: https://github.com/baraline/easyvista_python_client/compare/0.1.0...0.2.0
 [0.1.0]: https://github.com/baraline/easyvista_python_client/releases/tag/0.1.0

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: easyvista-python-client
-Version: 0.2.0
+Version: 0.3.0
 Summary: Typed Python client for the EasyVista Service Manager REST API
 Project-URL: Homepage, https://github.com/baraline/easyvista_python_client
 Project-URL: Documentation, https://easyvista-python-client.readthedocs.io/en/latest/
@@ -64,7 +64,10 @@ Typed Python client for the EasyVista Service Manager REST API. Sync + async,
 Pydantic models, Bearer or Basic auth.
 
 While the package is preparing for 1.0, breaking changes may land between
-minor versions; a deprecation policy will follow the 1.0 release.
+**minor** versions; a deprecation policy will follow the 1.0 release. A patch
+release never carries one. Each breaking change is marked `**BREAKING**` in its
+`CHANGELOG.md` section with the reasoning, so read the section for the version
+you are moving to.
 
 ## Documentation
 

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/README.md

@@ -11,7 +11,10 @@ Typed Python client for the EasyVista Service Manager REST API. Sync + async,
 Pydantic models, Bearer or Basic auth.
 
 While the package is preparing for 1.0, breaking changes may land between
-minor versions; a deprecation policy will follow the 1.0 release.
+**minor** versions; a deprecation policy will follow the 1.0 release. A patch
+release never carries one. Each breaking change is marked `**BREAKING**` in its
+`CHANGELOG.md` section with the reasoning, so read the section for the version
+you are moving to.
 
 ## Documentation
 

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/docs/publishing.rst

@@ -27,11 +27,23 @@ Cutting a release
 #. Move the ``CHANGELOG.md`` ``[Unreleased]`` entries under the new version and update the
    compare links at the bottom of the file.
 #. Merge to ``main`` and let CI go green.
-#. Publish a GitHub release whose tag is the version, ``v``-prefixed --
-   ``v0.2.0`` for version ``0.2.0``. (The workflow strips a leading ``v`` before comparing,
-   so an unprefixed tag also passes. The only tag that exists today, ``0.1.0``, is
-   **unprefixed** -- ``v``-prefixing starts at ``v0.2.0``, which is why the
-   ``CHANGELOG.md`` link for ``0.1.0`` points at the bare tag.)
+#. Publish a GitHub release whose tag is the version, **unprefixed** -- ``0.3.0``
+   for version ``0.3.0``, never ``v0.3.0``.
+
+   .. warning::
+
+      This step previously ordered a ``v``-prefixed tag and said "``v``-prefixing
+      starts at ``v0.2.0``". That never happened: **both tags that exist are
+      bare** -- ``0.1.0`` and ``0.2.0`` -- so following the old instruction would
+      have produced a repository with two tag conventions. It also left the
+      ``CHANGELOG.md`` compare links pointing at a ``v0.2.0`` that does not
+      exist, so two of them 404ed until 0.3.0 fixed them.
+
+      **The tag is what defines a version**; the prose is corrected to match the
+      tags, not the other way round. Keep every tag bare, and keep the
+      ``CHANGELOG.md`` links bare with it. (The release workflow strips a leading
+      ``v`` before comparing, so a prefixed tag would still *build* -- which is
+      exactly why this drifted unnoticed.)
 
 The workflow then runs the test matrix (3.10--3.14) and the quality gates -- Ruff, mypy,
 the generated-``_sync``-tree check, the hand-written-twin lint and a warnings-as-errors

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/docs/user_guide.rst

@@ -1160,7 +1160,8 @@ Timestamps
 ``Request``'s timestamp fields (``submit_date_ut``, ``creation_date_ut``,
 ``max_resolution_date_ut``, ``expected_date_ut``, ``end_date_ut``,
 ``last_update``), ``Employee.last_update``, and ``Action.created_at`` /
-``Action.updated_at`` are timezone-aware
+``Action.updated_at`` / ``Action.start_date_ut`` / ``Action.end_date_ut`` are
+timezone-aware
 :class:`datetime.datetime`, parsed from EasyVista's ISO-8601-with-offset wire
 format (``2026-08-17T15:40:41.610+02:00``, millisecond precision — verified
 live 2026-08-17). An unset date is ``None``. The ``_UT`` suffix is a naming
@@ -1193,14 +1194,29 @@ is still the raw wire string, so within one record dump
    ``json.dumps(record.model_dump(by_alias=True))`` and
    ``json.dumps(record.classify_fields().official)`` raise
    ``TypeError: Object of type datetime is not JSON serializable``. For a dump,
-   pass ``model_dump(mode="json")``. ``classify_fields()`` takes **no arguments**,
-   so there is nowhere to put that keyword: render the ``datetime`` values with
-   :func:`~easyvista_python_client.format_ev_datetime` before serialising the
-   bucket, or classify the JSON-mode dump yourself — the buckets are keyed by
-   wire column name, so ``{k: dumped[k] for k in record.classify_fields().official}``
-   over ``dumped = record.model_dump(mode="json", by_alias=True)`` gives the same
+   pass ``model_dump(mode="json")``.
+
+   **Since 0.3.0 an ``Action`` can also carry a ``Decimal``** — ``time_cost``
+   and ``contractual_cost`` — which raises the same way
+   (``TypeError: Object of type Decimal is not JSON serializable``).
+   ``model_dump(mode="json")`` handles it too, rendering the amount as a string.
+
+   ``classify_fields()`` takes **no arguments**, so there is nowhere to put that
+   keyword. The only recipe that covers *both* types is to classify the
+   JSON-mode dump yourself — the buckets are keyed by wire column name, so
+   ``{k: dumped[k] for k in record.classify_fields().official}`` over
+   ``dumped = record.model_dump(mode="json", by_alias=True)`` gives the same
    split with serialisable values.
 
+   .. warning::
+
+      Rendering the bucket with
+      :func:`~easyvista_python_client.format_ev_datetime` — which earlier
+      revisions of this page offered as the alternative — **only ever handled
+      ``datetime``**, and now leaves a ``Decimal`` in place to raise on
+      ``json.dumps``. Use the JSON-mode dump above instead. Note the amount then
+      renders with a ``.`` decimal point, not the ``,`` the API sent.
+
 Use :func:`~easyvista_python_client.format_ev_datetime` to render a
 ``datetime`` back into the literal EasyVista's grammar accepts (e.g. as an
 interval bound above), and :func:`~easyvista_python_client.parse_ev_datetime`

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/docs/vendor-api-reference.md

@@ -104,6 +104,114 @@ and not proof of it; it omits `group_id`, `group_name` and `comment`, which
 it lists `available_field_1`/`_6`, which `PostTask` does not declare and which
 `extra_payload` reaches.
 
+### A task is write-only as a resource, and read back as an action
+
+**Tier 2, read 2026-09-02** on the development instance (100 paths), and
+independently the same day on a second deployment (also 2025.3, also 100
+paths). Both declare exactly:
+
+| Path | Verbs |
+| --- | --- |
+| `/requests/{rfc_number}/tasks` | **POST only** |
+| `/requests/{rfc_number}/actions` | POST only |
+| `/actions` | GET |
+| `/actions/{id}` | GET, PATCH, PUT |
+| `/actions/{id}/{comment}` | GET |
+
+There is **no read route for a task** — no `GET /requests/{rfc}/tasks`, no
+`/tasks/{id}`, nothing under any other spelling. The only timeline reads are
+the three `/actions` routes. So a task is *written* through `tasks` and *read
+back* through `actions`, and that is the whole story: a task and an action are
+the same row in the same table, differing only in the state they are born in
+(open vs already ended). This is why the package has `list_actions` and
+deliberately **no `list_tasks`/`iter_tasks`** — there is no route to wrap.
+
+A GET against the tasks path answers `403 "Unauthorized Method for your
+profile"`, which per *Route topology* above proves nothing either way; the
+spec's `paths` is what settles it.
+
+**`create_task` returns an `Action`.** That is where a reader first meets the
+confusion, and the annotation is correct rather than sloppy: there is no task
+resource to model, so there is no `Task` read model and could not be one.
+
+### The effort columns, and why they do not discriminate task from action
+
+Five columns on an action record — `ELAPSED_TIME`, `TIME_COST`,
+`CONTRACTUAL_COST`, `START_DATE_UT`, `END_DATE_UT` — are declared on `Action`
+as of 0.3.0. Until then they arrived only as `extra="allow"` extras: untyped
+strings, with a French decimal comma on the two costs.
+
+**Tier 4, measured 2026-09-02, 1500 action rows on the development instance**
+(one instance, one date, so it may not generalise), corroborated by an
+independent measurement the same day on that second deployment (1465 timeline
+entries across 120 tickets), which agreed on every point below.
+
+**`""` and `"0"` are different answers.** `""` means the column does not apply
+to this record; `"0"` (or `"0,00"`) means it applies and is zero.
+
+| Column | `""` | zero | non-zero |
+| --- | --- | --- | --- |
+| `ELAPSED_TIME` | 384 | 895 (`'0'`) | 221 |
+| `TIME_COST` | 691 | 808 (`'0,00'`) | 1 (`'99,00'`) |
+| `CONTRACTUAL_COST` | 691 | 808 (`'0,00'`) | 1 (`'129,00'`) |
+
+A parser that maps both to `0`, or both to `None`, destroys the only signal
+that says whether a record tracks effort. `Action` preserves it: `None` for
+`""`, `0` / `Decimal("0.00")` for the zeroes.
+
+**The shape heuristic is false in both directions.** It is tempting to read
+"workflow rows carry `WORKFLOW_ID`/`STAGE_ID` with `ELAPSED_TIME='0'` and
+`'0,00'` costs, task-shaped rows carry none of it and empty effort" as a
+task/action discriminator. Measured, it fails both ways:
+
+* **173 of 1500** rows carried a `WORKFLOW_ID` *and* an empty `ELAPSED_TIME`
+  — 126 of them the type-20 `Analyse et résolution` workflow step. So
+  "workflow row ⇒ effort is `'0'`" is false.
+* **171 of 1500** rows carried no `WORKFLOW_ID` *and* a non-empty
+  `ELAPSED_TIME`. Among them **39 of the 49** type-94 `Commentaire [Public]`
+  rows — ordinary public comments — usually with `ELAPSED_TIME='1'`. One
+  public comment carried `ELAPSED_TIME='12'`, `TIME_COST='99,00'` and
+  `CONTRACTUAL_COST='129,00'`. So "effort recorded ⇒ not a comment" is false,
+  and a filter built on it drops four public comments in five.
+
+`ACTION_TYPE_ID` alone does not discriminate either, which the second
+deployment measured directly: type 94 appeared in both shapes there (74 rows
+with a `PARENT_ACTION_ID`, 18 without; 37 with a non-zero `ELAPSED_TIME`, 55
+without).
+
+What an effort column reports is **whether effort was recorded**, not what kind
+of record this is. No column examined across those 1500 rows recorded which
+route created it — stated as a measurement, not as a proof of absence: the
+item-level record carries 88 columns, not all of which were tallied, and a
+deployment may populate one this instance leaves empty. If you find a column
+that does discriminate, it belongs here.
+
+**What *is* clean: `WORKFLOW_ID`.** 1500/1500 rows — a `WORKFLOW_ID` is set iff
+the workflow engine produced the row. No row of the conversation types (94
+`Commentaire [Public]`, 95 `Note Interne [Privé]`, 7 `Appel`) carried one.
+`Action.is_workflow_generated` exposes exactly that and nothing more. Deciding
+which of the remaining types count as conversation is per-deployment policy —
+an `action_type_id` allowlist — and stays with the caller.
+
+**Side finding, tier 4, same measurement: `ACTION_LABEL_*` is the label of the
+workflow *step*, not the name of the action type.** Type 20 appeared as
+`Analyse et résolution` (126 rows), `Traitement` (10), `Traitement du refus`,
+`Traitement de la demande`, `test` and `notif`; type 30 as `stocker le groupe
+d'implémentation`, `Mise à jour SLA` and `sauvegarde`; type 82 under two
+labels. So for **workflow** types the label varies row to row and cannot be
+used as a type name. For the non-workflow types (94, 95, 7) it was stable and
+is the type's real name. This qualifies the *Visibility is by action type*
+note: `discover("ACTION_TYPE")` recovers real names for the human types, and
+per-step text for the workflow ones.
+
+**Types 14, 27 and 28 have an empty `ACTION_LABEL_*` in every language column**
+— all six on the list projection and all twelve (`_EN`, `_FR`, `_GE`, `_IT`,
+`_PO`, `_SP`, `_L1`..`_L6`) on the item GET. There is no `action-types` route
+to ask, so on this deployment those ids **cannot be named through the API at
+all**. What is known about 28 is behavioural, not nominal: it is the row that
+carries the text passed to `set_status(comment=...)`, so it must not be
+filtered out of a timeline read.
+
 Also worth recording without acting on it: the instance's `POST /assets` schema
 (tier 3) titles its array `asset` while its own example uses `assets`, which is
 what this package sends and what works. That is an inconsistency inside one
@@ -143,8 +251,10 @@ spec's `paths` is what settles whether a route exists.
 | Path | Verbs | Note |
 | --- | --- | --- |
 | `/requests/{rfc_number}/actions` | POST | create-only; no nested list, item or update |
+| `/requests/{rfc_number}/tasks` | POST | create-only; **no task read route exists** — read them back through `/actions` |
 | `/actions` | GET | the only action list |
 | `/actions/{id}` | GET, PATCH, PUT | the only action item; **no DELETE** |
+| `/actions/{id}/{comment}` | GET | `{comment}` is a memo-field *selector*, not a literal |
 | `/requests/{RFC_NUMBER}/documents` | GET, POST | |
 | `/requests/{RFC_NUMBER}/documents/{id}` | GET, DELETE | what this package sends by default |
 | `/documents/{id}` | GET, DELETE | marked `deprecated`; opt in with `document_delete_path_style="top_level"` |
@@ -217,6 +327,27 @@ The vendor documents `catalog_guid` as the *preferred* identifier (tier 1) and
   docstrings now hedge. Until someone either re-reads the vendor page and adds
   the row here, or measures the omitted form live and dates it, the
   documentation must not assert it.
+* **O-COSTGROUP** — `TIME_COST` / `CONTRACTUAL_COST` are parsed by
+  `models/common._parse_ev_decimal`, which accepts either decimal separator and
+  **refuses a grouping separator** rather than guessing (`'1.234,56'` and
+  `'1,234.56'` are the same amount under opposite conventions). Every amount
+  observed live had exactly two fraction digits and no grouping (1500 rows,
+  2026-09-02), so the refusal has never fired. It **also** refuses three or more
+  fraction digits, for the same ambiguity (`'1,234'` could be `1.234` or a
+  comma-grouped `1234`) — which means a genuinely 3-decimal currency is refused
+  too. **Magnitude is not a trigger**: `'1000,00'` parses fine, since it carries
+  no grouping separator. Because the descriptor validates a page in a list
+  comprehension, a refusal fails a whole `list_actions` call, not one row. If a
+  refused literal is ever seen, record it here and widen the pattern with
+  evidence.
+* **O-ACTIONTYPE28** — types 14, 27 and 28 have an empty `ACTION_LABEL_*` in
+  every language column at both list and item level, and there is no
+  `action-types` route, so nothing in the API can name them. Type 28 is known
+  behaviourally (it carries `set_status(comment=...)` text) and 14 and 27 not
+  at all. Settling this needs the EasyVista **admin console**, not the API: the
+  administration screen listing action types, and specifically which type ids
+  that deployment classes as *task* types. Nobody working on this package has
+  console access; if you do, transcribe the list here.
 * **O-TASKDOC** — transcribe the vendor's create-a-task field table into the
   section above, so `PostTask` can be diffed against tier 1. Until then
   `action_type_guid` is declared on `PostAction` (tier 1, 2023.4+) and **not**

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/easyvista_python_client/_async/client.py

@@ -629,6 +629,27 @@ class AsyncEasyvistaClient:
         no ``parent_action_id`` and works on a ticket at any stage, including
         one whose open actions a status change has already drained.
 
+        **This returns an** :class:`~easyvista_python_client.Action`, and that
+        is not a mistake in the annotation: a task *is* an action record, and
+        there is no separate task resource to model. ``tasks`` is a create-only
+        route — the instance's own OpenAPI declares
+        ``POST /requests/{rfc_number}/tasks`` and no other verb on it, and
+        declares no read route for a task anywhere (tier 2, read 2026-09-02 on
+        one deployment, 100 paths, and independently on a second the same day).
+        The only timeline reads are ``GET /actions``, ``GET /actions/{id}`` and
+        ``GET /actions/{id}/{comment}``, so **a task is written as a task and
+        read back as an action** — which is why this package has
+        :meth:`list_actions` and no ``list_tasks``. A GET against the tasks
+        path answers 403, and per
+        ``docs/vendor-api-reference.md`` no 403 on this API distinguishes an
+        absent route from a denied one, so the spec is what settles it.
+
+        A corollary worth stating, because it is where the read side goes
+        wrong: **once written, nothing on the record says which route created
+        it.** In particular the effort columns do not — see
+        :attr:`~easyvista_python_client.Action.is_workflow_generated` for the
+        measurements that refute the tempting heuristic.
+
         Like :meth:`create_action`, the returned :class:`Action` carries **no
         usable ``action_id``** — the create response is an HREF naming the
         parent request. Diff :meth:`list_actions` across the call to address

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/easyvista_python_client/_sync/client.py

@@ -629,6 +629,27 @@ class EasyvistaClient:
         no ``parent_action_id`` and works on a ticket at any stage, including
         one whose open actions a status change has already drained.
 
+        **This returns an** :class:`~easyvista_python_client.Action`, and that
+        is not a mistake in the annotation: a task *is* an action record, and
+        there is no separate task resource to model. ``tasks`` is a create-only
+        route — the instance's own OpenAPI declares
+        ``POST /requests/{rfc_number}/tasks`` and no other verb on it, and
+        declares no read route for a task anywhere (tier 2, read 2026-09-02 on
+        one deployment, 100 paths, and independently on a second the same day).
+        The only timeline reads are ``GET /actions``, ``GET /actions/{id}`` and
+        ``GET /actions/{id}/{comment}``, so **a task is written as a task and
+        read back as an action** — which is why this package has
+        :meth:`list_actions` and no ``list_tasks``. A GET against the tasks
+        path answers 403, and per
+        ``docs/vendor-api-reference.md`` no 403 on this API distinguishes an
+        absent route from a denied one, so the spec is what settles it.
+
+        A corollary worth stating, because it is where the read side goes
+        wrong: **once written, nothing on the record says which route created
+        it.** In particular the effort columns do not — see
+        :attr:`~easyvista_python_client.Action.is_workflow_generated` for the
+        measurements that refute the tempting heuristic.
+
         Like :meth:`create_action`, the returned :class:`Action` carries **no
         usable ``action_id``** — the create response is an HREF naming the
         parent request. Diff :meth:`list_actions` across the call to address

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/easyvista_python_client/_version.py

@@ -5,4 +5,4 @@
 live only in ``__init__``.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/easyvista_python_client/models/action.py

@@ -11,6 +11,7 @@ from .common import (
     EasyvistaModel,
     EasyvistaWriteModel,
     OptionalDateTime,
+    OptionalDecimal,
     OptionalInt,
     _shipped_keys,
 )
@@ -42,6 +43,42 @@ class Action(EasyvistaModel):
     request instead of an item fetch per action — ``list_actions`` returns one
     page and does not paginate, so it is a page's worth, not a ticket's.
 
+    **Effort columns: ``""`` and ``"0"`` are different answers.** ``elapsed_time``
+    (minutes), ``time_cost``, ``contractual_cost``, ``start_date_ut`` and
+    ``end_date_ut`` are declared as of 0.3.0, having previously reached callers
+    only as untyped ``extra="allow"`` strings. When the API **returns** the
+    column, ``""`` means it does not apply to this record and ``"0"`` /
+    ``"0,00"`` means it applies and is zero (tier 4, measured 2026-09-02 over
+    1500 rows on two instances -- so it may not generalise). This model preserves
+    that distinction deliberately -- ``None`` for ``""``, ``0`` /
+    ``Decimal("0.00")`` for the zeroes -- because collapsing the two destroys the
+    only signal saying whether a record tracks effort at all. The two cost columns
+    arrive with a French decimal comma (``'99,00'``) and parse to an exact
+    :class:`~decimal.Decimal`. Either decimal separator is accepted; a grouping
+    separator and three-or-more fraction digits are **refused** rather than
+    guessed at, because ``'1.234,56'`` and ``'1,234.56'`` are the same amount
+    under opposite conventions. Magnitude is not a trigger -- ``'1000,00'``
+    parses. The parser is ``models/common.py::_parse_ev_decimal``, named as a
+    path rather than cross-referenced because it is private and carries no
+    rendered API-reference page.
+
+    .. warning::
+
+       **``None`` is ambiguous, and the default list row is the trap.** None of
+       these five columns rides the default ``list_actions`` projection, so on a
+       default list row every one of them reads ``None`` -- meaning *not
+       returned*, not *does not apply*. The two are indistinguishable on the
+       model. Project them explicitly (``list_actions(rfc, fields=[...,
+       "ELAPSED_TIME", "WORKFLOW_ID"])``) or read item-level with
+       :meth:`~easyvista_python_client.EasyvistaClient.get_action` before reading
+       any meaning into a ``None``. To tell the two apart from a raw response,
+       check whether the key is present at all -- once validated, that is gone.
+
+    What that signal does **not** settle is whether a row was created as a task
+    or as an action -- nothing on the record does, and the effort-shape heuristic
+    that looks like it should is measurably wrong in both directions. See
+    :attr:`is_workflow_generated`.
+
     Naming: this model calls its two timestamps ``created_at``/``updated_at``
     where :class:`~easyvista_python_client.models.request.Request` and
     :class:`~easyvista_python_client.models.employee.Employee` mirror the wire
@@ -103,6 +140,29 @@ class Action(EasyvistaModel):
     stage_id: OptionalInt = Field(default=None, alias="STAGE_ID")
     workflow_id: OptionalInt = Field(default=None, alias="WORKFLOW_ID")
     parent_action_id: OptionalInt = Field(default=None, alias="PARENT_ACTION_ID")
+    # --- effort and cost (EV-TASKSHAPE, added 0.3.0) -------------------------
+    # Until 0.3.0 these five reached callers only as untyped ``extra="allow"``
+    # strings. **The "" sentinel and "0" are different answers** -- "" means the
+    # column does not apply to this record, "0" that it applies and is zero --
+    # and ``OptionalInt``/``OptionalDecimal`` preserve exactly that: ``None`` for
+    # "", ``0`` for "0". Measured over 1500 live rows 2026-09-02, ELAPSED_TIME
+    # was "" on 384 and "0" on 895; the costs were "" on 691 and "0,00" on 808.
+    #
+    # ``elapsed_time`` is in MINUTES, is never derived from the window, and is
+    # stored verbatim even when it contradicts it -- but a zero-length window
+    # (``start_date_ut == end_date_ut``) stores 0 whatever was sent.
+    #
+    # Named for the wire (``start_date_ut``/``end_date_ut``) to match
+    # ``Request.end_date_ut``, rather than following this model's own
+    # ``created_at``/``updated_at``, which the class docstring flags as a wart.
+    # Both are the ACTION's effort window: unlike ``Request.end_date_ut``, which
+    # is stamped at RESOLUTION, an action's ``END_DATE_UT`` is set when the
+    # action itself is ended.
+    elapsed_time: OptionalInt = Field(default=None, alias="ELAPSED_TIME")
+    time_cost: OptionalDecimal = Field(default=None, alias="TIME_COST")
+    contractual_cost: OptionalDecimal = Field(default=None, alias="CONTRACTUAL_COST")
+    start_date_ut: OptionalDateTime = Field(default=None, alias="START_DATE_UT")
+    end_date_ut: OptionalDateTime = Field(default=None, alias="END_DATE_UT")
 
     @model_validator(mode="after")
     def _derive_action_id_from_href(self) -> Action:
@@ -150,6 +210,58 @@ class Action(EasyvistaModel):
         """
         return localized_label(self.model_dump(by_alias=True), "ACTION_LABEL")
 
+    @property
+    def is_workflow_generated(self) -> bool:
+        """Whether the workflow engine owns this row, i.e. ``WORKFLOW_ID`` is set.
+
+        A ticket's catalog workflow auto-spawns its own action rows -- about a
+        dozen on a freshly created ticket -- and each carries a ``WORKFLOW_ID``
+        naming the workflow instance. Rows created by a person or by an API
+        caller do not. Measured 2026-09-02 over 1500 live action rows on one
+        instance (tier 4, so it may not generalise): no row of the
+        conversation-bearing types (94 ``Commentaire [Public]``, 95 ``Note
+        Interne [Prive]``, 7 ``Appel``) carried one, and every row of the
+        workflow step types (1, 20, 21, 23, 30, 32, 33, 50, 65, 82, 84) that
+        the engine had produced did.
+
+        .. warning::
+
+           **This is not a task/action discriminator, and there is none.** A
+           task (``create_task``) and an action (``create_action``) are the same
+           record in the same table, told apart only by the state they are born
+           in -- open versus already ended -- and **neither ``WORKFLOW_ID`` nor
+           the effort columns recover which route created a row**. Measured
+           2026-09-02, both directions of the tempting shape heuristic fail on
+           one instance:
+
+           * 173 of 1500 rows had a ``WORKFLOW_ID`` **and** an empty
+             ``ELAPSED_TIME`` -- 126 of them the type-20 ``Analyse et
+             resolution`` workflow step. So "workflow row => effort is 0" is
+             false.
+           * 39 of 49 type-94 ``Commentaire [Public]`` rows -- ordinary public
+             comments -- carried a **non-empty** ``ELAPSED_TIME``, usually
+             ``'1'``; one carried ``ELAPSED_TIME='12'``, ``TIME_COST='99,00'``
+             and ``CONTRACTUAL_COST='129,00'``. So "effort set => not a
+             comment" is false, and a filter built on it drops four public
+             comments in five.
+
+           What an effort column reports is whether *effort was recorded*, not
+           what kind of record this is. Deciding which action types count as
+           conversation is per-deployment policy: pin the ``action_type_id``
+           allowlist your administrator confirms, and use this property only to
+           exclude the workflow engine's own rows. See
+           ``docs/vendor-api-reference.md`` for the measurements.
+
+        A plain property, not a serialized field, so it never appears in
+        ``model_dump`` or ``classify_fields``. ``False``, never ``None``, when
+        ``WORKFLOW_ID`` is absent from the projection -- the default
+        ``list_actions`` row omits it, so on a default list row this reads
+        ``False`` for every action whether or not the engine owns it. Project
+        ``WORKFLOW_ID`` explicitly (``list_actions(rfc,
+        fields=[..., "WORKFLOW_ID"])``) or read item-level before trusting it.
+        """
+        return self.workflow_id is not None
+
 
 class PostAction(EasyvistaWriteModel):
     """Payload for creating an action on a ticket.

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/easyvista_python_client/models/common.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
+import re
 from collections.abc import Sequence
 from datetime import datetime, timezone
+from decimal import Decimal
 from typing import Annotated, Any
 
 from pydantic import (
@@ -37,6 +39,88 @@ OptionalInt = Annotated[int | None, BeforeValidator(_empty_str_to_none)]
 """An ``int | None`` field that treats the API's ``""`` sentinel as ``None``."""
 
 
+# An optional sign, digits, then at most one separator and one or two fraction
+# digits. Deliberately refuses a grouping separator -- see the validator.
+_EV_DECIMAL = re.compile(r"^[+-]?\d+(?:[.,]\d{1,2})?$")
+
+
+def _parse_ev_decimal(value: Any) -> Any:
+    """Parse EasyVista's locale-formatted money column into an exact ``Decimal``.
+
+    The instance renders a currency column with its own decimal separator: on
+    the verified deployment ``TIME_COST`` and ``CONTRACTUAL_COST`` come back as
+    ``'0,00'`` / ``'99,00'`` — a **comma** — which is why this exists rather
+    than the column being a plain ``float``. Both separators are accepted, so a
+    dot-configured deployment needs no setting; the separator is a deployment's
+    locale, not an EasyVista constant.
+
+    ``""`` maps to ``None`` and that is load-bearing: ``""`` means the column
+    does **not apply** to this record, while ``'0,00'`` means it applies and is
+    zero. Collapsing the two — to ``0`` or to ``None`` — destroys the only
+    signal that says whether a record tracks cost at all. See
+    :class:`~easyvista_python_client.models.action.Action` for what that signal
+    is worth and what it does **not** prove.
+
+    **Two shapes raise rather than being guessed at**, both of them formats this
+    parser has never seen live:
+
+    * **A grouping separator.** ``'1.234,56'`` and ``'1,234.56'`` are the same
+      amount under opposite conventions, and ``'9,999'`` is either ``9.999`` or
+      ``9999`` with nothing in the value to say which.
+    * **Three or more fraction digits.** ``'1,234'`` is refused for the same
+      reason — it is indistinguishable from a comma-grouped ``1234`` — which
+      also means a genuinely 3-decimal currency is refused here.
+
+    Note what is **not** a trigger: magnitude. ``'1000,00'`` parses fine, because
+    it carries no grouping separator. An earlier revision of this docstring said
+    "an amount above 999 is the case to watch", which was wrong — what matters is
+    the *format*, not the size.
+
+    Every amount observed live carried exactly two fraction digits and no
+    grouping (1500 rows, 2026-09-02: ``'0,00'``, ``'99,00'``, ``'129,00'``).
+    Refusing is the same trade :func:`_empty_str_to_none_datetime` makes — a
+    wrong number is worse than a loud failure — and it carries the same cost:
+    ``resources/descriptor.py`` validates a page in a list comprehension, so one
+    unparseable amount fails the whole ``list_actions`` call rather than that
+    row. See ``O-COSTGROUP`` in ``docs/vendor-api-reference.md``.
+
+    ``Decimal``, not ``float``, because these are money: ``Decimal('0.10') +
+    Decimal('0.20') == Decimal('0.30')`` and the float equivalent does not.
+    A non-string value (an ``int``, ``float`` or ``Decimal`` handed in
+    directly) passes through to pydantic's own ``Decimal`` validator untouched.
+    """
+    if value is None:
+        return None
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return None
+        if not _EV_DECIMAL.match(text):
+            raise ValueError(
+                f"{value!r} is not an EasyVista amount. Expected digits with at "
+                "most one decimal separator ('.' or ',') and ONE OR TWO "
+                "fraction digits, e.g. '0,00' or '99.00'. Refused, rather than "
+                "guessed at: a grouping separator (because '1.234,56' and "
+                "'1,234.56' are the same amount under opposite conventions), and "
+                "three or more fraction digits (because '1,234' is "
+                "indistinguishable from a comma-grouped 1234). Magnitude is not "
+                "a trigger -- '1000,00' parses. If this instance really formats "
+                "amounts this way, that is a finding worth recording -- report "
+                "the value."
+            )
+        return Decimal(text.replace(",", "."))
+    return value
+
+
+OptionalDecimal = Annotated[Decimal | None, BeforeValidator(_parse_ev_decimal)]
+"""An exact ``Decimal | None`` for an EasyVista currency column.
+
+Accepts either decimal separator and maps the ``""`` sentinel to ``None``,
+which is **not** the same answer as ``Decimal('0.00')`` — see
+:func:`_parse_ev_decimal`.
+"""
+
+
 def _parse_with_context_formats(value: Any, info: ValidationInfo) -> datetime | None:
     """Try the caller's own timestamp formats, if it supplied any.
 

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/easyvista_python_client/references.py

@@ -26,6 +26,7 @@ from __future__ import annotations
 from collections.abc import Iterator, Sequence
 from dataclasses import dataclass
 from datetime import datetime
+from decimal import Decimal
 from functools import lru_cache
 from typing import Any
 
@@ -141,7 +142,14 @@ def _scalar(value: Any) -> str | None:
             return format_ev_datetime(value)
         except ValueError:
             return value.isoformat()
-    if isinstance(value, (str, int)) and str(value).strip():
+    # ``Decimal`` joins ``str``/``int`` here because the read path retypes the
+    # currency columns (``TIME_COST``, ``CONTRACTUAL_COST``) into exact
+    # ``Decimal``s. Without this branch ``reference("TIME_COST")`` returned an
+    # EMPTY Reference on a populated column -- the same class of silent gap the
+    # ``datetime`` branch above was added to close. Rendered with ``str`` rather
+    # than the wire's own decimal comma: this extractor feeds labels and
+    # identifiers, not money formatting, and it must never raise.
+    if isinstance(value, (str, int, Decimal)) and str(value).strip():
         return str(value).strip()
     return None
 

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/pyproject.toml

@@ -44,7 +44,7 @@ exclude = [
 
 [project]
 name = "easyvista-python-client"
-version = "0.2.0"
+version = "0.3.0"
 description = "Typed Python client for the EasyVista Service Manager REST API"
 readme = "README.md"
 requires-python = ">=3.10"

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/skills/easyvista-asset-workflow/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.10+, easyvista-python-client, network access to an EasyVista Service Manager REST API, and a profile authorized for the assets resource."
 metadata:
   package: easyvista-python-client
-  version: "0.2.0"
+  version: "0.3.0"
 ---
 
 > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`,

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/skills/easyvista-client-setup/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.10+, easyvista-python-client, network access to an EasyVista Service Manager REST API, and valid EasyVista credentials."
 metadata:
   package: easyvista-python-client
-  version: "0.2.0"
+  version: "0.3.0"
 ---
 
 `easyvista_python_client` ships both clients over one surface:

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/skills/easyvista-directory/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.10+, easyvista-python-client, network access to an EasyVista Service Manager REST API, and a profile authorized for the departments and employees resources (writes are additionally profile-gated)."
 metadata:
   package: easyvista-python-client
-  version: "0.2.0"
+  version: "0.3.0"
 ---
 
 > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`,

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/skills/easyvista-document-workflow/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.10+, easyvista-python-client, network access to an EasyVista Service Manager REST API, and a profile authorized for the documents sub-resource."
 metadata:
   package: easyvista-python-client
-  version: "0.2.0"
+  version: "0.3.0"
 ---
 
 > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`,

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/skills/easyvista-instance-discovery/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.10+, easyvista-python-client, and network access to an EasyVista Service Manager REST API. Every call here is a GET; nothing is created, updated or deleted."
 metadata:
   package: easyvista-python-client
-  version: "0.2.0"
+  version: "0.3.0"
 ---
 
 > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`,

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/skills/easyvista-reporting-and-context/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.10+, easyvista-python-client, and network access to an EasyVista Service Manager REST API."
 metadata:
   package: easyvista-python-client
-  version: "0.2.0"
+  version: "0.3.0"
 ---
 
 > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`,

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/skills/easyvista-search-syntax/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.10+, easyvista-python-client, and network access to an EasyVista Service Manager REST API."
 metadata:
   package: easyvista-python-client
-  version: "0.2.0"
+  version: "0.3.0"
 ---
 
 > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`,

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/skills/easyvista-ticket-actions/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.10+, easyvista-python-client, network access to an EasyVista Service Manager REST API, and a profile authorized for the actions sub-resource."
 metadata:
   package: easyvista-python-client
-  version: "0.2.0"
+  version: "0.3.0"
 ---
 
 > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`,
@@ -130,6 +130,43 @@ Verified live 2026-08-28: tasks came back with `END_DATE_UT` and
 mandatory; `PostTask` refuses a body missing either rather than letting the
 server answer with a 590 that names no field.
 
+**A task is write-only as a resource.** `POST requests/{rfc}/tasks` is the only
+verb the route has, and the API declares **no task read route at all** (tier 2,
+read 2026-09-02 on two 2025.3 deployments). So `create_task` returns an
+`Action`, there is no `Task` read model and no `list_tasks` — a task is written
+as a task and read back through `list_actions` like any other row. A GET against
+the tasks path answers 403, which on this API proves nothing either way.
+
+**No action-record column observed so far says which route created it**, so do
+not try to reconstruct the distinction on the read side. In particular the effort
+columns do not: measured over 1500 live rows 2026-09-02, 39 of 49
+`Commentaire [Public]` comments carried a non-empty `ELAPSED_TIME` (one with
+`TIME_COST='99,00'`), while 173 workflow rows carried an empty one. To pick
+conversation out of a timeline, filter on an `action_type_id` allowlist your
+administrator confirms, and use `action.is_workflow_generated` to drop the
+workflow engine's own rows.
+
+**`is_workflow_generated` needs `WORKFLOW_ID` projected, or it is always
+`False`.** It reads that one column, and the column is NOT on the default
+`list_actions` projection — so on default rows the filter silently drops nothing
+and every workflow row survives. The same applies to all five effort columns:
+unprojected they read `None`, which is indistinguishable from the `''` that means
+"does not apply". Ask for them:
+
+```python
+actions = client.iter_actions(
+    "YOUR_RFC_NUMBER",
+    fields=[
+        "ACTION_ID", "ACTION_TYPE_ID", "WORKFLOW_ID",
+        "ELAPSED_TIME", "START_DATE_UT", "END_DATE_UT",
+    ],
+)
+conversation = [
+    a for a in actions
+    if not a.is_workflow_generated and a.action_type_id in YOUR_COMMENT_TYPE_IDS
+]
+```
+
 **If a caller creates an action and stops**, nothing is lost — the text is
 stored — but the row renders without it until the action is ended. Use
 **`end_action`**, which wraps the vendor's `PUT actions/{rfc_number}` /
@@ -532,3 +569,20 @@ with EasyvistaClient.from_env() as client:
   columns. `getattr(record, "last_update")` raises `AttributeError` on an
   `Action`; for code spanning record types, go through `classify_fields()` or
   `.reference()`, where the wire alias is uniform.
+- **On the effort columns, `''` and `'0'` are different answers.**
+  `elapsed_time` (minutes), `time_cost`, `contractual_cost`, `start_date_ut` and
+  `end_date_ut` are declared as of 0.3.0. `''` means the column does not apply
+  to this record and reads as `None`; `'0'` / `'0,00'` means it applies and is
+  zero, and reads as `0` / `Decimal("0.00")`. Do not normalise the two together
+  — that erases the only signal saying whether a record tracks effort at all.
+  The costs are exact `Decimal`s parsed from the API's decimal comma; an amount
+  with a grouping separator raises rather than being guessed at, and because a
+  page is validated all at once that fails the whole `list_actions` call.
+- **`ACTION_LABEL_*` is the workflow STEP's label, not the action type's name**
+  (measured 2026-09-02, 1500 rows). Type 20 appeared under six labels:
+  `Analyse et résolution`, `Traitement`, `Traitement du refus`, `Traitement de
+  la demande`, `test` and `notif`. For the non-workflow
+  types (94, 95, 7) it is stable and is the real type name; for workflow types
+  it varies row to row, so never key on it. Types 14, 27 and 28 have an empty
+  label in every language column at both list and item level — the API cannot
+  name them, and only the admin console can.

{easyvista_python_client-0.2.0 → easyvista_python_client-0.3.0}/skills/easyvista-ticket-workflow/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.10+, easyvista-python-client, network access to an EasyVista Service Manager REST API, and a profile authorized for the requests resource."
 metadata:
   package: easyvista-python-client
-  version: "0.2.0"
+  version: "0.3.0"
 ---
 
 > **Sync and async.** Examples use `EasyvistaClient`. For `AsyncEasyvistaClient`,