valentina-python-client 3.2.0__tar.gz → 3.4.0__tar.gz

{valentina_python_client-3.2.0 → valentina_python_client-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: valentina-python-client
-Version: 3.2.0
+Version: 3.4.0
 Summary: Async Python client library for the Valentina Noir API
 Author: Nate Landau
 Author-email: Nate Landau <github@natenate.org>
@@ -15,11 +15,12 @@ License: MIT License
          THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: anyio>=4.14.1,<5.0.0
-Requires-Dist: httpx2>=2.5.0
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: anyio>=4.15.1,<5.0.0
+Requires-Dist: httpx2>=2.13.1
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: polyfactory>=3.3.0,<4.0.0
-Requires-Dist: pydantic[email]>=2.13.4,<3.0.0
+Requires-Dist: pydantic[email]>=2.14.1,<3.0.0
 Requires-Dist: polyfactory>=3.3.0 ; extra == 'testing'
 Requires-Python: >=3.13
 Project-URL: Homepage, https://docs.valentina-noir.com/python-api-client/

valentina_python_client-3.4.0/pyproject.toml

@@ -0,0 +1,244 @@
+[project]
+classifiers = [
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+dependencies = [
+    "anyio>=4.15.1,<5.0.0",
+    "httpx2>=2.13.1",
+    "loguru>=0.7.3",
+    "polyfactory>=3.3.0, <4.0.0",
+    "pydantic[email]>=2.14.1,<3.0.0",
+]
+description = "Async Python client library for the Valentina Noir API"
+name = "valentina-python-client"
+readme = "README.md"
+requires-python = ">=3.13"
+version = "3.4.0"
+
+[[project.authors]]
+name = "Nate Landau"
+email = "github@natenate.org"
+
+[project.license]
+file = "LICENSE"
+
+[project.optional-dependencies]
+testing = ["polyfactory>=3.3.0"]
+
+[project.urls]
+Homepage = "https://docs.valentina-noir.com/python-api-client/"
+Repository = "https://github.com/natelandau/valentina-python-client"
+
+[build-system]
+build-backend = "uv_build"
+requires = ["uv_build>=0.13.0,<0.14"]
+
+[tool.uv.build-backend]
+module-name = "vclient"
+
+[tool.commitizen]
+bump_message = "bump(release): v$current_version → v$new_version"
+changelog_merge_prerelease = true
+tag_format = "v$version"
+update_changelog_on_bump = true
+version_files = ["src/vclient/__init__.py:__version__"]
+version_provider = "uv"
+
+[tool.coverage.report]
+exclude_lines = [
+    "def __repr__",
+    'except [\w\s\._]+ as .*:',
+    "if TYPE_CHECKING",
+    "pragma: no cover",
+    "raise Abort",
+    "raise Exit",
+]
+fail_under = 0
+precision = 1
+show_missing = true
+skip_covered = true
+skip_empty = true
+
+[tool.coverage.run]
+branch = true
+command_line = "--module pytest"
+data_file = ".cache/coverage"
+omit = ["tests/*"]
+source = ["src"]
+
+[tool.coverage.xml]
+output = ".cache/coverage.xml"
+
+[tool.pytest.ini_options]
+addopts = "--color=yes --doctest-modules --strict-config --strict-markers -n auto --dist loadfile"
+cache_dir = ".cache/pytest"
+filterwarnings = [
+    "error",
+    "ignore:.*Pydantic.*:UserWarning",
+    "ignore::DeprecationWarning:",
+]
+markers = ["serial"]
+testpaths = ["tests"]
+xfail_strict = true
+
+[tool.ruff]
+exclude = [
+    ".cache",
+    ".dev",
+    ".git",
+    ".venv",
+    ".worktrees",
+    "_build",
+    "_site",
+    "build",
+    "dist",
+]
+fix = true
+line-length = 100
+output-format = "grouped"
+src = [
+    "src",
+    "tests",
+]
+target-version = "py313"
+
+[tool.ruff.lint]
+ignore = [
+    "ANN002",
+    "ANN003",
+    "ANN204",
+    "ANN401",
+    "B006",
+    "B008",
+    "COM812",
+    "CPY001",
+    "D107",
+    "E501",
+    "PLC0415",
+    "E711",
+    "E712",
+    "FIX002",
+    "S311",
+    "TD001",
+    "TD002",
+    "TD003",
+]
+select = ["ALL"]
+unfixable = [
+    "ERA001",
+    "F401",
+    "F841",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/vclient/_sync/**" = [
+    "C416",
+    "C901",
+    "D",
+    "E501",
+    "ERA001",
+    "PLR0913",
+    "PLR2004",
+    "PLW0603",
+    "SLF001",
+    "TRY300",
+    "UP028",
+]
+"scripts/*.py" = [
+    "INP001",
+    "T201",
+]
+"src/vclient/services/*.py" = ["PLR0913"]
+"src/vclient/validate_constants.py" = ["T201"]
+"tests/**/*.py" = [
+    "A002",
+    "A003",
+    "ANN001",
+    "ANN002",
+    "ANN003",
+    "ANN201",
+    "ARG001",
+    "ARG002",
+    "ARG005",
+    "D102",
+    "ERA001",
+    "F403",
+    "F405",
+    "FBT001",
+    "PGH003",
+    "PLC0415",
+    "PLR0913",
+    "PLR0917",
+    "PLR2004",
+    "PT011",
+    "S101",
+    "SLF001",
+    "W292",
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.pylint]
+max-args = 6
+
+[tool.ruff.format]
+exclude = ["src/vclient/_sync"]
+indent-style = "space"
+line-ending = "auto"
+quote-style = "double"
+skip-magic-trailing-comma = false
+
+[tool.vulture]
+exclude = [
+    "duties.py",
+    "scripts/",
+    "tests/",
+    "tmp/",
+]
+ignore_decorators = []
+ignore_names = []
+make_whitelist = false
+min_confidence = 100
+paths = ["src/"]
+sort_by_size = true
+verbose = false
+
+[tool.ty.terminal]
+error-on-warning = true
+
+[dependency-groups]
+dev = [
+    "commitizen>=4.19.2",
+    "coverage>=7.16.2",
+    "duty>=1.10.1",
+    "gate-cache>=0.6.0",
+    "httpx>=0.28.1",
+    "prek>=0.5.5",
+    "pytest-anyio>=0.0.0",
+    "pytest-clarity>=1.0.1",
+    "pytest-cov>=7.1.0",
+    "pytest-devtools>=1.3.0",
+    "pytest-httpx2>=1.0.0",
+    "pytest-mock>=3.16.0",
+    "pytest-repeat>=0.9.4",
+    "pytest-sugar>=1.1.1",
+    "pytest-xdist>=3.8.0",
+    "pytest>=9.1.1",
+    "respx>=0.23.1",
+    "ruff>=0.17.0",
+    "shellcheck-py>=0.11.0.1",
+    "ty>=0.0.86",
+    "typos>=1.51.1",
+    "vulture>=2.16",
+    "yamllint>=1.38.0",
+]
+docs = ["zensical>=0.0.70"]

valentina_python_client-3.2.0/pyproject.toml → valentina_python_client-3.4.0/pyproject.toml.orig

@@ -3,20 +3,21 @@
     classifiers = [
         "Programming Language :: Python :: 3.13",
         "Programming Language :: Python :: 3.14",
+        "Programming Language :: Python :: 3.15",
     ]
     dependencies = [
-        "anyio>=4.14.1,<5.0.0",
-        "httpx2>=2.5.0",
+        "anyio>=4.15.1,<5.0.0",
+        "httpx2>=2.13.1",
         "loguru>=0.7.3",
         "polyfactory>=3.3.0, <4.0.0",
-        "pydantic[email]>=2.13.4, <3.0.0",
+        "pydantic[email]>=2.14.1,<3.0.0",
     ]
     description = "Async Python client library for the Valentina Noir API"
     license = { file = "LICENSE" }
     name = "valentina-python-client"
     readme = "README.md"
     requires-python = ">=3.13"
-    version = "3.2.0"
+    version = "3.4.0"
 
     [project.optional-dependencies]
         testing = ["polyfactory>=3.3.0"]
@@ -27,37 +28,38 @@
 
 [build-system]
     build-backend = "uv_build"
-    requires      = ["uv_build>=0.11.15,<0.12.0"]
+    requires      = ["uv_build>=0.13.0,<0.14"]
 
 [tool.uv.build-backend]
     module-name = "vclient"
 
 [dependency-groups]
     dev = [
-        "commitizen>=4.16.4",
-        "coverage>=7.15.0",
-        "duty>=1.9.0",
+        "commitizen>=4.19.2",
+        "coverage>=7.16.2",
+        "duty>=1.10.1",
+        "gate-cache>=0.6.0",
         "httpx>=0.28.1",
-        "prek>=0.4.8",
+        "prek>=0.5.5",
         "pytest-anyio>=0.0.0",
         "pytest-clarity>=1.0.1",
         "pytest-cov>=7.1.0",
-        "pytest-devtools>=1.2.0",
+        "pytest-devtools>=1.3.0",
         "pytest-httpx2>=1.0.0",
-        "pytest-mock>=3.15.1",
+        "pytest-mock>=3.16.0",
         "pytest-repeat>=0.9.4",
         "pytest-sugar>=1.1.1",
         "pytest-xdist>=3.8.0",
         "pytest>=9.1.1",
         "respx>=0.23.1",
-        "ruff>=0.15.20",
+        "ruff>=0.17.0",
         "shellcheck-py>=0.11.0.1",
-        "ty>=0.0.56",
-        "typos>=1.48.0",
+        "ty>=0.0.86",
+        "typos>=1.51.1",
         "vulture>=2.16",
         "yamllint>=1.38.0",
-    ]
-    docs = ["zensical>=0.0.47"]
+]
+    docs = ["zensical>=0.0.70"]
 
 [tool.commitizen]
     bump_message               = "bump(release): v$current_version → v$new_version"
@@ -168,7 +170,8 @@
             "FBT001",  # Boolean-typed positional argument in function definition
             "PGH003",  # Use specific rule codes when ignoring type issues
             "PLC0415", # Imports should be at top of file
-            "PLR0913",
+            "PLR0913", # Too many positional arguments
+            "PLR0917", # Too many positional arguments
             "PLR2004",
             "PT011",   # set the `match` parameter or use a more specific exception
             "S101",

{valentina_python_client-3.2.0 → valentina_python_client-3.4.0}/src/vclient/__init__.py

@@ -31,7 +31,7 @@ _logger.add(
     # Forward TRACE too (e.g. the "Send request" line) and let the consumer's
     # stdlib logging level decide what to show; the sink must not pre-filter it.
     level="TRACE",
-    filter=lambda record: record["name"].startswith("vclient"),
+    filter=lambda record: record["name"].startswith("vclient"),  # ty: ignore[unresolved-attribute]
 )
 
 _logger.disable("vclient")
@@ -116,4 +116,4 @@ __all__ = (
     "users_service",
 )
 
-__version__ = "3.2.0"
+__version__ = "3.4.0"

{valentina_python_client-3.2.0 → valentina_python_client-3.4.0}/src/vclient/_sync/services/campaigns.py

@@ -127,6 +127,7 @@ class SyncCampaignsService(SyncBaseService):
             request: A CampaignCreate model, OR pass fields as keyword arguments.
             **kwargs: Fields for CampaignCreate if request is not provided.
                 Accepts: name (str, required), description (str | None),
+                in_game_date (datetime.date | None, ISO 8601 calendar date),
                 desperation (int, default 0), danger (int, default 0).
 
         Returns:
@@ -154,7 +155,8 @@ class SyncCampaignsService(SyncBaseService):
             request: A CampaignUpdate model, OR pass fields as keyword arguments.
             **kwargs: Fields for CampaignUpdate if request is not provided.
                 Accepts: name (str | None), description (str | None),
-                desperation (int | None), danger (int | None).
+                in_game_date (datetime.date | None, ISO 8601 calendar date;
+                pass None to clear it), desperation (int | None), danger (int | None).
 
         Returns:
             The updated Campaign object.
@@ -166,9 +168,11 @@ class SyncCampaignsService(SyncBaseService):
             ValidationError: If the request data is invalid.
         """
         body = request if request is not None else self._validate_request(CampaignUpdate, **kwargs)
+        payload = body.model_dump(exclude_none=True, exclude_unset=True, mode="json")
+        if "in_game_date" in body.model_fields_set and body.in_game_date is None:
+            payload["in_game_date"] = None
         response = self._patch(
-            self._format_endpoint(Endpoints.CAMPAIGN, campaign_id=campaign_id),
-            json=body.model_dump(exclude_none=True, exclude_unset=True, mode="json"),
+            self._format_endpoint(Endpoints.CAMPAIGN, campaign_id=campaign_id), json=payload
         )
         return Campaign.model_validate(response.json())
 

{valentina_python_client-3.2.0 → valentina_python_client-3.4.0}/src/vclient/_sync/services/character_traits.py

@@ -5,15 +5,21 @@ from collections.abc import Iterator
 from typing import TYPE_CHECKING
 
 from vclient._sync.services.base import SyncBaseService
-from vclient.constants import DEFAULT_PAGE_LIMIT, TraitModifyCurrency
+from vclient.constants import DEFAULT_PAGE_LIMIT, DamageType, TrackerAction, TraitModifyCurrency
 from vclient.endpoints import Endpoints
 from vclient.models import (
+    _TRACKER_ADAPTER,
     BulkAssignTraitResponse,
     CharacterTrait,
     CharacterTraitAdd,
+    CharacterTraitSpecialtyCreate,
+    CharacterTraitSpecialtyUpdate,
     CharacterTraitValueOptionsResponse,
     PaginatedResponse,
+    Tracker,
+    TrackerStateSet,
     TraitCreate,
+    _TrackerAction,
     _TraitModify,
 )
 
@@ -140,6 +146,8 @@ class SyncCharacterTraitsService(SyncBaseService):
     def delete(self, character_trait_id: str, currency: TraitModifyCurrency | None = None) -> None:
         """Delete a character trait.
 
+        Any specialties on the trait are removed with it and the cost of each is refunded.
+
         Args:
             character_trait_id: The ID of the trait to delete.
             currency: The currency to use to recoup the cost of the trait.
@@ -152,6 +160,8 @@ class SyncCharacterTraitsService(SyncBaseService):
             AuthorizationError: If you don't have access to the character.
             RequestValidationError: If the input parameters fail client-side validation.
             ValidationError: If the request data is invalid.
+            ConflictError: If recouping ``XP`` or ``STARTING_POINTS`` and another request
+                changed the trait's value first. Refetch the trait and retry.
         """
         params: dict[str, str | int] = {}
         if currency is not None:
@@ -177,6 +187,8 @@ class SyncCharacterTraitsService(SyncBaseService):
             AuthorizationError: If you don't have access to the character.
             RequestValidationError: If the input parameters fail client-side validation.
             ValidationError: If the request data is invalid.
+            ConflictError: If paying with ``XP`` or ``STARTING_POINTS`` and another request
+                changed the trait's value first. Refetch the trait and retry.
         """
         body = self._validate_request(
             CharacterTraitAdd, trait_id=trait_id, value=value, currency=currency
@@ -222,8 +234,16 @@ class SyncCharacterTraitsService(SyncBaseService):
             **kwargs: Fields for TraitCreate if request is not provided.
                 Required: name (str), category_id (str), currency (TraitModifyCurrency).
                 Optional: description (str | None), max_value (int), min_value (int),
-                show_when_zero (bool), initial_cost (int | None),
-                upgrade_cost (int | None).
+                show_when_zero (bool), is_rollable (bool, default True),
+                initial_cost (int | None), upgrade_cost (int | None),
+                count_based_cost_multiplier (int | None).
+
+        Returns:
+            The newly created CharacterTrait object.
+
+        Raises:
+            ConflictError: If paying with ``XP`` or ``STARTING_POINTS`` and another request
+                changed the trait's value first. Refetch the trait and retry.
         """
         body = request if request is not None else self._validate_request(TraitCreate, **kwargs)
         response = self._post(
@@ -259,10 +279,20 @@ class SyncCharacterTraitsService(SyncBaseService):
     ) -> CharacterTrait:
         """Change the value of a character trait.
 
+        Lowering an ability to ``0`` also removes its specialties and refunds the cost of
+        each. The value change and the refunds are applied together or not at all.
+
         Args:
             character_trait_id: The ID of the trait to change the value of.
             new_value: The new value of the trait.
             currency: The currency to use for the modification.
+
+        Returns:
+            The updated CharacterTrait object.
+
+        Raises:
+            ConflictError: If another request changed the trait's value after this request
+                read it. Nothing is spent or refunded. Refetch the trait and retry.
         """
         body = self._validate_request(_TraitModify, target_value=new_value, currency=currency)
         response = self._put(
@@ -272,3 +302,197 @@ class SyncCharacterTraitsService(SyncBaseService):
             json=body.model_dump(exclude_none=True, exclude_unset=True, mode="json"),
         )
         return CharacterTrait.model_validate(response.json())
+
+    def add_specialty(
+        self, character_trait_id: str, name: str, currency: TraitModifyCurrency = "NO_COST"
+    ) -> CharacterTrait:
+        """Add a specialty to an ability trait.
+
+        Specialties are only available on abilities with a value of 1 or higher. When the
+        company's ``specialty_xp_cost_enabled`` setting is on, a specialty paid with ``XP``
+        or ``STARTING_POINTS`` costs 3 points, and ``NO_COST`` follows the company's
+        ``permission_free_trait_changes`` setting. When the setting is off, specialties are free.
+
+        Args:
+            character_trait_id: The ID of the ability trait.
+            name: The specialty name (3-50 characters), unique on the trait ignoring case.
+            currency: The currency to use to pay for the specialty.
+
+        Returns:
+            The updated CharacterTrait object, including its specialties.
+
+        Raises:
+            NotFoundError: If the trait does not exist.
+            AuthorizationError: If you don't have access to the character.
+            RequestValidationError: If the input parameters fail client-side validation.
+            ValidationError: If the trait is not an ability, has a value of 0, already has a
+                specialty with this name, the character cannot afford the cost, or an
+                ``NPC`` or ``STORYTELLER`` character pays with anything but ``NO_COST``.
+        """
+        body = self._validate_request(CharacterTraitSpecialtyCreate, name=name, currency=currency)
+        response = self._post(
+            self._format_endpoint(
+                Endpoints.CHARACTER_TRAIT_SPECIALTIES, character_trait_id=character_trait_id
+            ),
+            json=body.model_dump(exclude_none=True, mode="json"),
+        )
+        return CharacterTrait.model_validate(response.json())
+
+    def update_specialty(
+        self, character_trait_id: str, specialty_id: str, name: str
+    ) -> CharacterTrait:
+        """Rename a specialty on an ability trait.
+
+        Renaming never changes the cost paid or the currency used.
+
+        Args:
+            character_trait_id: The ID of the ability trait.
+            specialty_id: The ID of the specialty to rename.
+            name: The new specialty name (3-50 characters), unique on the trait ignoring case.
+
+        Returns:
+            The updated CharacterTrait object, including its specialties.
+
+        Raises:
+            NotFoundError: If the trait or specialty does not exist, or the specialty
+                belongs to a different trait.
+            AuthorizationError: If you don't have access to the character.
+            RequestValidationError: If the input parameters fail client-side validation.
+            ValidationError: If the trait already has a specialty with this name.
+        """
+        body = self._validate_request(CharacterTraitSpecialtyUpdate, name=name)
+        response = self._patch(
+            self._format_endpoint(
+                Endpoints.CHARACTER_TRAIT_SPECIALTY,
+                character_trait_id=character_trait_id,
+                specialty_id=specialty_id,
+            ),
+            json=body.model_dump(exclude_none=True, mode="json"),
+        )
+        return CharacterTrait.model_validate(response.json())
+
+    def delete_specialty(self, character_trait_id: str, specialty_id: str) -> None:
+        """Remove a specialty from an ability trait.
+
+        The cost paid is refunded in the currency used to buy it. An ``XP`` refund follows
+        the company's ``permission_recoup_xp`` setting; starting points are always refunded.
+
+        Args:
+            character_trait_id: The ID of the ability trait.
+            specialty_id: The ID of the specialty to remove.
+
+        Returns:
+            None
+
+        Raises:
+            NotFoundError: If the trait or specialty does not exist, or the specialty
+                belongs to a different trait.
+            AuthorizationError: If you don't have access to the character.
+        """
+        self._delete(
+            self._format_endpoint(
+                Endpoints.CHARACTER_TRAIT_SPECIALTY,
+                character_trait_id=character_trait_id,
+                specialty_id=specialty_id,
+            )
+        )
+
+    def get_tracker(self, character_trait_id: str) -> Tracker:
+        """Get the in-play tracker state of a character trait.
+
+        The same object appears as ``CharacterTrait.tracker``. Use this to refresh one
+        tracker without fetching the whole trait.
+
+        Args:
+            character_trait_id: The ID of the character trait.
+
+        Returns:
+            A CounterTracker, DamageTracker, or StainsTracker. Switch on ``type``.
+
+        Raises:
+            NotFoundError: If the trait has no tracker for the character's game version.
+            AuthorizationError: If you don't have access to the character.
+        """
+        response = self._get(
+            self._format_endpoint(
+                Endpoints.CHARACTER_TRAIT_TRACKER, character_trait_id=character_trait_id
+            )
+        )
+        return _TRACKER_ADAPTER.validate_python(response.json())
+
+    def set_tracker(
+        self, character_trait_id: str, request: TrackerStateSet | None = None, **kwargs
+    ) -> Tracker:
+        """Replace the full state of a trait tracker, such as to correct a mistake.
+
+        Send only the fields for the tracker's type: ``current`` for counters (required),
+        ``superficial`` and ``aggravated`` for damage tracks, ``stains`` for stains. Omitted
+        fields reset to 0, so an empty request clears a damage or stains tracker. Use
+        ``apply_tracker_action`` for in-play changes instead.
+
+        Args:
+            character_trait_id: The ID of the character trait.
+            request: A TrackerStateSet model, OR pass fields as keyword arguments.
+            **kwargs: Fields for TrackerStateSet if request is not provided.
+                Accepts: current, superficial, aggravated, stains (int >= 0).
+
+        Returns:
+            The updated tracker.
+
+        Raises:
+            NotFoundError: If the trait has no tracker for the character's game version.
+            AuthorizationError: If you are not the character's player or a storyteller.
+            RequestValidationError: If a value is negative.
+            ValidationError: If a field does not fit the tracker type, a counter has no
+                ``current``, or a value exceeds the tracker size.
+        """
+        body = request if request is not None else self._validate_request(TrackerStateSet, **kwargs)
+        response = self._put(
+            self._format_endpoint(
+                Endpoints.CHARACTER_TRAIT_TRACKER, character_trait_id=character_trait_id
+            ),
+            json=body.model_dump(exclude_none=True, mode="json"),
+        )
+        return _TRACKER_ADAPTER.validate_python(response.json())
+
+    def apply_tracker_action(
+        self,
+        character_trait_id: str,
+        action: TrackerAction,
+        *,
+        amount: int = 1,
+        damage_type: DamageType | None = None,
+    ) -> Tracker:
+        """Apply one in-play action to a trait tracker, such as spending Willpower.
+
+        The server applies the game rules for the character's game version. Which actions
+        and damage types fit each tracker is listed in ``characters.TrackerRules`` from
+        ``options.get_options()``. A STAINS response reports overflow into Willpower in
+        ``willpower_damage_applied``.
+
+        Args:
+            character_trait_id: The ID of the character trait.
+            action: The action to apply.
+            amount: How many points to apply. Must be at least 1.
+            damage_type: The damage type for ``damage`` and ``heal`` on damage tracks.
+
+        Returns:
+            The updated tracker.
+
+        Raises:
+            NotFoundError: If the trait has no tracker for the character's game version.
+            AuthorizationError: If you are not the character's player or a storyteller.
+            RequestValidationError: If ``amount`` is less than 1.
+            ValidationError: If the action or damage type does not fit the tracker, a
+                damage type is missing or not allowed, or a spend exceeds the current value.
+        """
+        body = self._validate_request(
+            _TrackerAction, action=action, amount=amount, damage_type=damage_type
+        )
+        response = self._post(
+            self._format_endpoint(
+                Endpoints.CHARACTER_TRAIT_TRACKER_ACTIONS, character_trait_id=character_trait_id
+            ),
+            json=body.model_dump(exclude_none=True, mode="json"),
+        )
+        return _TRACKER_ADAPTER.validate_python(response.json())