glpi-python-client 0.4.1__tar.gz → 0.4.2__tar.gz

{glpi_python_client-0.4.1 → glpi_python_client-0.4.2}/CONTRIBUTING.md

@@ -38,7 +38,7 @@ python -m sphinx -W --keep-going -b html docs docs/_build/html
 
 ## GitHub Actions
 
-- `.github/workflows/ci.yml` runs tests for Python 3.10 through 3.13 on pull
+- `.github/workflows/ci.yml` runs tests for Python 3.10 through 3.14 on pull
   requests and pushes to `main`.
 - The same workflow runs `ruff`, `mypy`, and a warning-free Sphinx build on
   Python 3.12.

{glpi_python_client-0.4.1 → glpi_python_client-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glpi-python-client
-Version: 0.4.1
+Version: 0.4.2
 Summary: A typed Python client for GLPI ITSM APIs.
 Project-URL: Homepage, https://github.com/baraline/glpi_python_client
 Project-URL: Documentation, https://glpi-python-client.readthedocs.io/en/latest/
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed

{glpi_python_client-0.4.1 → glpi_python_client-0.4.2}/docs/publishing_rtd.rst

@@ -92,7 +92,7 @@ GitHub Actions and Read the Docs
 The repository ships with two GitHub Actions workflows:
 
 * ``.github/workflows/ci.yml`` runs on pull requests and pushes to ``main``.
-   It executes ``pytest`` on Python 3.10 through 3.13, then runs ``ruff``,
+   It executes ``pytest`` on Python 3.10 through 3.14, then runs ``ruff``,
    ``mypy``, and the Sphinx build on Python 3.12.
 * ``.github/workflows/release.yml`` runs on published GitHub releases. It
    repeats the quality checks, builds the source and wheel distributions,

{glpi_python_client-0.4.1 → glpi_python_client-0.4.2}/glpi_python_client/__init__.py

@@ -104,7 +104,7 @@ from glpi_python_client.models import (
     TicketMarkdownOptions,
 )
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 
 __all__ = [
     "AsyncGlpiClient",

{glpi_python_client-0.4.1 → glpi_python_client-0.4.2}/pyproject.toml

@@ -35,7 +35,7 @@ exclude = [
 
 [project]
 name = "glpi-python-client"
-version = "0.4.1"
+version = "0.4.2"
 description = "A typed Python client for GLPI ITSM APIs."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -52,6 +52,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Internet :: WWW/HTTP",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",

{glpi_python_client-0.4.1 → glpi_python_client-0.4.2}/skills/README.md

@@ -10,11 +10,13 @@ These skills are source-tree project material. They are included in source distr
 | --- | --- | --- |
 | `glpi-client-setup` | Build and configure an authenticated client | `GlpiClient`, `AsyncGlpiClient`, `.from_env()` |
 | `glpi-ticket-workflow` | Search, fetch, create, update, or delete tickets | `GetTicket`, `PostTicket`, `PatchTicket`, `DeleteTicket` |
-| `glpi-ticket-timeline` | Read timeline records or write followups, tasks, solutions, and document links | `PostFollowup`, `PostTicketTask`, `PostSolution`, `PostTimelineDocument` (plus matching Get/Patch/Delete) |
+| `glpi-ticket-timeline` | Read timeline records or write followups, tasks, solutions, and document links | `PostFollowup`, `PostTicketTask`, `PostSolution`, `PostTimelineDocument` (plus matching Get/Patch/Delete for followups/tasks/solutions; document reads return `GetDocument`, not a `GetTimelineDocument`) |
 | `glpi-document-workflow` | Manage document metadata, upload binary content, download binaries | `GetDocument`, `PostDocument`, `PatchDocument`, `DeleteDocument` |
 | `glpi-user-location-provisioning` | Search and provision users, locations, and entities | `GetUser`, `PostUser`, `GetLocation`, `PostLocation`, `GetEntity`, `PostEntity` |
 | `glpi-reporting-and-context` | Aggregate ticket statistics, aggregate task durations, or load one ticket context bundle | `GlpiClient`, `GlpiTicketContext`, public enums |
 | `glpi-team-members` | List, add, or remove ticket team members | `GetTeamMember`, `PostTeamMember` |
+| `glpi-knowledge-base` | Search, read, or write KB articles, categories, comments, and revisions | `GetKBArticle`, `PostKBArticle`, `GetKBCategory`, `GetKBArticleComment`, `GetKBArticleRevision` |
+| `glpi-plugin-fields` | Discover and read/write Fields-plugin custom fields | `GetPluginFieldsContainer`, `GetPluginFieldsField`, `GetPluginFieldsValueRow` |
 
 ## Sync and async
 
@@ -23,6 +25,6 @@ The package ships two clients with identical endpoint surfaces:
 - `GlpiClient` — synchronous. `with GlpiClient(...) as client`, no `await`.
 - `AsyncGlpiClient` — asynchronous, performing real non-blocking I/O. `async with AsyncGlpiClient(...) as client`, `await` every method.
 
-Neither wraps the other: the async tree is hand-written and the synchronous one is generated from it by `unasync_build.py`, so the two cannot drift apart. The snippets in each skill are written against `AsyncGlpiClient`; every skill opens with a note on how to read them for the synchronous client.
+Neither wraps the other: the async tree is hand-written and the synchronous one is generated from it by `unasync_build.py`, so the two cannot drift apart. Every skill opens with a note telling you how to read its snippets across the two surfaces. For eight of the nine that note says the same thing -- the snippets are written against `AsyncGlpiClient`, so drop the `await` and the `async` for `GlpiClient`. `glpi-client-setup` is the exception and says so in its own note: choosing between the two clients is what that skill is *for*, so it shows both directly, side by side, and neither surface is a translation of the other.
 
 When fanning out concurrently on the async client, bound the fan-out with an `asyncio.Semaphore` — see `glpi-client-setup`. An unbounded fan-out is slower, not faster.

{glpi_python_client-0.4.1 → glpi_python_client-0.4.2}/skills/glpi-client-setup/SKILL.md

@@ -1,15 +1,21 @@
 ---
 name: glpi-client-setup
-description: "Create and configure the synchronous glpi_python_client.GlpiClient or the asynchronous glpi_python_client.AsyncGlpiClient, including from_env, OAuth credential pairs, entity/profile headers, SSL settings, and the optional legacy v1 document-upload session. Use before calling GLPI APIs or when the user asks how to connect to GLPI with glpi_python_client."
+description: "Create and configure the synchronous glpi_python_client.GlpiClient or the asynchronous glpi_python_client.AsyncGlpiClient, including from_env, OAuth credential pairs, entity/profile headers, SSL settings, and the optional legacy v1 session (v1_base_url / v1_user_token) that backs document uploads, the Fields plugin helpers, KB category writes and actor-based statistics. Use before calling GLPI APIs, when configuring the v1 session for any of those features, or when the user asks how to connect to GLPI with glpi_python_client."
 license: MIT
 compatibility: "Requires Python 3.10+, glpi-python-client, network access to a GLPI v2 API, and valid GLPI credentials."
 metadata:
   package: glpi-python-client
-  version: "0.4.0"
+  version: "0.4.1"
 ---
 
 # GLPI Client Setup
 
+> Unlike the other skills in this package, the snippets below are not written
+> against one client and translated for the other: `with GlpiClient(...)` and
+> `async with AsyncGlpiClient(...)` examples both appear directly, side by
+> side, because choosing between the two surfaces is what this skill is for.
+> Read each example as written for the client it names.
+
 The package exposes two clients with identical endpoint surfaces:
 
 - `glpi_python_client.GlpiClient` — synchronous, blocking client. Use it from
@@ -44,8 +50,22 @@ call `client.close()` (or `await client.close()`) when finished.
    `client_secret`, `username`/`password`, or both pairs together.
 5. Add `glpi_entity`, `glpi_profile`, and `entity_recursive=True` only
    when the operation must run in a specific GLPI scope.
-6. Add `v1_base_url` and `v1_user_token` only when binary document
-   uploads are needed (`upload_document`). `v1_app_token` is optional.
+6. Add `v1_base_url` and `v1_user_token` whenever a v1-backed feature is
+   used, not only for uploads. They are required by: binary document
+   uploads (`upload_document`); the Fields plugin helpers
+   (`get_ticket_custom_fields`, `set_ticket_custom_fields`,
+   `list_plugin_fields_containers`, `list_plugin_fields_fields`,
+   `list_item_plugin_field_rows`, `create_item_plugin_field_row`,
+   `update_item_plugin_field_row`); KB category writes
+   (`set_kb_article_categories`, and `PostKBArticle.categories` /
+   `PatchKBArticle.categories` passed to `create_kb_article` /
+   `update_kb_article`); and actor-based statistics
+   (`get_user_activity`, `get_task_durations(user_id=...)`) — v2 cannot
+   filter on a ticket's actors at all, so those resolve through the v1
+   search engine. The same session also switches `get_task_durations`
+   to a bulk v1 task sweep once a run covers 25 tickets or more. Any of
+   these raises `RuntimeError` when the v1 session is absent.
+   `v1_app_token` is optional.
 7. Keep `verify_ssl=True` unless the user explicitly confirms a test or
    internal endpoint that cannot validate TLS.
 8. Bound any large async fan-out with an `asyncio.Semaphore` on the
@@ -130,17 +150,25 @@ with GlpiClient.from_env() as glpi:
 Environment setup, asynchronous:
 
 ```python
+import asyncio
+
 from glpi_python_client import AsyncGlpiClient
 
-async with AsyncGlpiClient.from_env() as glpi:
-    tickets = await glpi.search_tickets("status==1")
+
+async def main() -> None:
+    async with AsyncGlpiClient.from_env() as glpi:
+        tickets = await glpi.search_tickets("status==1")
+
+
+asyncio.run(main())
 ```
 
-Document-upload setup (works on either client):
+Legacy v1 session setup — enables every v1-backed feature from step 6,
+not only uploads (works on either client):
 
 ```python
 with GlpiClient.from_env(
-    v1_base_url="https://glpi.example.com/apirest.php",
+    v1_base_url="https://glpi.example.com/api.php/v1",
     v1_user_token="legacy-user-token",
 ) as glpi:
     ...
@@ -154,10 +182,29 @@ with GlpiClient.from_env(
 - The package no longer exports `GLPIV1Session`. Configure
   `v1_base_url`/`v1_user_token` on the client and call
   `upload_document` instead.
-- Use `glpi_api_url` for the v2 API; `v1_base_url` is only for the
-  document-upload fallback.
+- Use `glpi_api_url` for the v2 API; `v1_base_url` additionally enables
+  every v1-backed feature listed in step 6 — document uploads, the
+  Fields plugin helpers, KB category writes and actor-based statistics.
 - Closing the client matters because it owns one or two HTTP sessions
   plus an OAuth token manager. Prefer the context-manager form.
+- Every **API** failure the library raises derives from `GlpiError`,
+  exported from the package root. Construction raises
+  `GlpiValidationError` for a missing `glpi_api_url`, a half-supplied
+  credential pair, or a `v1_base_url` without a `v1_user_token`; calls
+  raise `GlpiAuthError` (401/403), `GlpiNotFoundError` (404),
+  `GlpiServerError` (persistent 5xx),
+  `GlpiTransportError`/`GlpiTimeoutError` (network fault) or
+  `GlpiProtocolError` (unusable 2xx body). Do not catch `requests`
+  exceptions — `requests` is not a dependency — and do not catch
+  `tenacity.RetryError`; the retry decorators re-raise the real error.
+- A small set of raise sites is deliberately **outside** that hierarchy,
+  so `except GlpiError:` will not catch them. Plain `RuntimeError`:
+  using a closed client; a v1-backed call on a client built without
+  `v1_base_url`; and a `create_kb_article` whose category fallback
+  failed *after* the article was already created (the article exists,
+  its categories were not applied). Plain `TypeError`: an environment
+  value that is neither a string nor the expected scalar when `from_env`
+  parses an integer or boolean setting.
 - Concurrent callers cannot stampede the token endpoint: the client
   holds a lock around OAuth acquisition, so it is safe to launch a
   fan-out on `AsyncGlpiClient` before the token has ever been fetched.

{glpi_python_client-0.4.1 → glpi_python_client-0.4.2}/skills/glpi-document-workflow/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.10+, glpi-python-client, network access to the GLPI v2 API, and v1 credentials configured on the client for binary uploads."
 metadata:
   package: glpi-python-client
-  version: "0.4.0"
+  version: "0.4.1"
 ---
 
 # GLPI Document Workflow
@@ -25,7 +25,7 @@ The `GLPIV1Session` class is no longer part of the public surface; the v1 sessio
 6. Delete with `await client.delete_document(document_id, force=True|False|None)`.
 7. Download bytes with `content = await client.download_document_content(document_id)`.
 8. Upload bytes with `await client.upload_document(filename=..., content=..., mime_type=..., ticket_id=..., entity_id=...)`.
-9. To attach an existing GLPI document to a ticket timeline, use `link_ticket_timeline_document` from the timeline skill.
+9. To put a file on a ticket timeline, use `upload_document(..., ticket_id=...)` -- it creates the document *and* the ticket link in one call. `link_ticket_timeline_document` from the timeline skill cannot be told **which** existing document to link: `PostTimelineDocument` declares only `extra_payload` and `timeline_position`, and the POST URL carries only the ticket id, so there is no typed slot for a document id. See the timeline skill for the `extra_payload` escape hatch and its caveat.
 
 ## Examples
 
@@ -64,9 +64,10 @@ document_id = await client.create_document(PostDocument(name="Diagnostic notes")
 
 ## Gotchas
 
+- **`search_documents` swallows 4xx and returns `[]`.** This is a library-wide contract, not a document peculiarity: `_resource_list` checks the response status only when the caller passes a `failure_message`, and none of the seven `search_*` helpers (`search_documents`, `search_tickets`, `search_users`, `search_locations`, `search_entities`, `search_kb_articles`, `search_kb_categories`) passes one -- a GLPI error body is not a JSON list, so it is coerced to `[]`. A malformed RSQL filter, a 403 on `/Management/Document`, a missing route and "no such document" all look identical. `get_document`, `download_document_content` and every `list_*` helper do pass a `failure_message` and raise `GlpiStatusError` (narrowed to `GlpiAuthError` / `GlpiNotFoundError` / `GlpiServerError`) normally. So never conclude from an empty `search_documents` that a file is not on the server and re-upload it -- that is how duplicate documents get created; corroborate with a call that raises first.
 - `upload_document` raises `RuntimeError` when the v1 session is not configured. Pass `v1_base_url` and `v1_user_token` to the client constructor or `from_env`.
 - `upload_document` requires a non-empty `filename`. On the async client the multipart POST is awaited like any other call, so the event loop is not blocked.
 - `download_document_content` returns `bytes` and raises on non-200 responses.
 - `mime_type` defaults to `application/octet-stream` when omitted on `upload_document`.
-- All methods are async; always `await` them.
+- The snippets above use `AsyncGlpiClient`, so every call is awaited. The same methods on the synchronous `GlpiClient` are plain blocking calls -- drop the `await`.
 - The `delete_document(force=True)` flag permanently deletes; omit (or `False`) to move to the trash.

glpi_python_client-0.4.2/skills/glpi-knowledge-base/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: glpi-knowledge-base
+description: "Search, read, create, update, and delete GLPI knowledge base articles, categories, comments, and revisions with the synchronous glpi_python_client.GlpiClient or the asynchronous AsyncGlpiClient, and the GetKBArticle/PostKBArticle/GetKBCategory/GetKBArticleComment/GetKBArticleRevision models. Use for GLPI knowledge base content, FAQ articles, article categories, article comments, article revision history, or assigning categories to a KB article."
+license: MIT
+compatibility: "Requires Python 3.10+, glpi-python-client, network access to the GLPI v2 API, and — for category writes only — a legacy v1 session (v1_base_url + v1_user_token)."
+metadata:
+  package: glpi-python-client
+  version: "0.4.1"
+---
+
+# GLPI Knowledge Base
+> The snippets below use `AsyncGlpiClient` (`async with` + `await`). Every method shown also exists on the synchronous `GlpiClient` with the same signature -- replace `async with` with `with`, drop the `await` keyword, and skip the surrounding `async def`/`asyncio.run` scaffolding.
+
+The GLPI knowledge base lives under `/Knowledgebase/*` on the v2 API and covers four resources: articles, their categories, article comments, and article revisions. Eighteen methods expose them, present on both `GlpiClient` and `AsyncGlpiClient` with identical signatures. One operation -- assigning categories to an article -- is not a v2 call at all and needs a legacy v1 session; everything else in the family is pure v2.
+
+## Procedure
+
+1. Create a client from the `glpi-client-setup` skill. Add `v1_base_url` and `v1_user_token` **only** if you will write article categories.
+2. Articles: `search_kb_articles(rsql_filter, limit=..., start=..., sort=..., language=...)` for lists and `get_kb_article(article_id)` for one. Write with `create_kb_article(PostKBArticle(...))` (returns the new id), `update_kb_article(article_id, PatchKBArticle(...))` and `delete_kb_article(article_id, force=...)` (both return `None`).
+3. Article categories: `set_kb_article_categories(article_id, category_ids)`. The ids **replace** the whole set; an empty sequence clears it. Ids are not validated against the server -- an unknown id is simply not linked.
+4. Categories: `search_kb_categories(...)` (same parameters as the article search), `get_kb_category(category_id)`, `create_kb_category(PostKBCategory(...))`, `update_kb_category(category_id, PatchKBCategory(...))`, `delete_kb_category(category_id, force=...)`. `completename` and `level` are server-managed and absent from the write models.
+5. Comments: `list_kb_article_comments(article_id)`, `get_kb_article_comment(article_id, comment_id)`, `create_kb_article_comment(article_id, PostKBArticleComment(...))` (returns the new id), `update_kb_article_comment(article_id, comment_id, PatchKBArticleComment(...))`, `delete_kb_article_comment(article_id, comment_id, force=...)`. The parent article comes from the URL, so `PostKBArticleComment` has no `kbarticle` field.
+6. Revisions, read-only: `list_kb_article_revisions(article_id, language=...)` then `get_kb_article_revision(article_id, revision, language=...)`.
+7. Refetch with `get_kb_article()` when the task needs a populated model after a write.
+
+## Examples
+
+Create a category and a categorised article. `v1_base_url`/`v1_user_token` are required here **only** because the article carries `categories`:
+
+```python
+from glpi_python_client import AsyncGlpiClient, IdNameRef, PostKBArticle, PostKBCategory
+
+async with AsyncGlpiClient(
+    glpi_api_url="https://glpi.example.com/api.php/v2",
+    client_id="oauth-client-id",
+    client_secret="oauth-client-secret",
+    v1_base_url="https://glpi.example.com/api.php/v1",
+    v1_user_token="legacy-user-token",
+) as client:
+    category_id = await client.create_kb_category(
+        PostKBCategory(name="Network", comment="Networking runbooks")
+    )
+    # content/description are Markdown here and HTML on the wire.
+    article_id = await client.create_kb_article(
+        PostKBArticle(
+            name="Reset a password",
+            content="Run **passwd**, then check `logs`.",
+            description="A *short* summary.",
+            is_faq=True,
+            categories=[IdNameRef(id=category_id)],  # IdRef would not validate
+        )
+    )
+```
+
+Recover from the non-atomic create. There is no rollback: on failure the article exists and its id is only available from the message text:
+
+```python
+import re
+
+from glpi_python_client import AsyncGlpiClient, PostKBArticle
+
+
+async def create_with_categories(client: AsyncGlpiClient, article: PostKBArticle) -> int:
+    """Create `article`, re-linking its categories if the fallback failed.
+
+    The retry presupposes a configured v1 session: when the missing session
+    is itself the cause, `set_kb_article_categories` raises the same
+    `RuntimeError` again. It helps only for a transient legacy failure.
+    """
+    try:
+        return await client.create_kb_article(article)
+    except RuntimeError as exc:  # plain builtin, NOT a GlpiError
+        match = re.search(r"KB article (\d+) was created", str(exc))
+        if match is None:
+            raise
+        article_id = int(match.group(1))
+        # The v2 article is intact; retry only the legacy category link.
+        # Derive the ids from the model -- they are the same list that
+        # triggered the fallback, so the retry cannot link nothing.
+        await client.set_kb_article_categories(
+            article_id, [c.id for c in article.categories or [] if c.id is not None]
+        )
+        return article_id
+```
+
+Search, and disambiguate an empty result. `language` is a query parameter on both search helpers:
+
+```python
+from glpi_python_client import GlpiNotFoundError
+
+faq = await client.search_kb_articles(
+    "is_faq==1", limit=25, start=0, sort="date_mod desc", language="fr_FR"
+)
+categories = await client.search_kb_categories("name==Network", limit=10)
+print([(c.id, c.completename) for c in categories])
+
+# A search never raises on a 4xx -- it returns []. To tell 'no matches'
+# from 'this GLPI serves no /Knowledgebase routes', probe an article you
+# know exists. Only the SUCCEEDING branch is informative: a 404 is raised
+# both by an absent route and by an absent id, so it proves nothing.
+if not faq:
+    known_article_id = 1  # an article known to exist on this instance
+    try:
+        await client.get_kb_article(known_article_id)
+    except GlpiNotFoundError:
+        print("inconclusive: no such article, or no /Knowledgebase routes")
+    else:
+        print("the endpoint is served -- the filter simply matched nothing")
+```
+
+Comments and revisions on one article:
+
+```python
+from glpi_python_client import PatchKBArticleComment, PostKBArticleComment
+
+# `comment` is plain text -- no Markdown conversion, unlike article content.
+comment_id = await client.create_kb_article_comment(
+    5, PostKBArticleComment(comment="Confirmed on GLPI 11.")
+)
+await client.update_kb_article_comment(
+    5, comment_id, PatchKBArticleComment(comment="Edited.")
+)
+one = await client.get_kb_article_comment(5, comment_id)
+for listed in await client.list_kb_article_comments(5):
+    print(listed.id, listed.comment)
+await client.delete_kb_article_comment(5, comment_id, force=True)
+
+# `language` is a PATH SEGMENT here: Knowledgebase/Article/5/fr_FR/Revision
+revisions = await client.list_kb_article_revisions(5, language="fr_FR")
+if revisions and revisions[0].revision is not None:
+    revision = await client.get_kb_article_revision(
+        5, revisions[0].revision, language="fr_FR"  # the revision NUMBER
+    )
+    print(revision.revision, revision.content)  # content comes back as Markdown
+```
+
+Category maintenance is pure v2 -- no legacy session is involved:
+
+```python
+from glpi_python_client import IdNameRef, PatchKBCategory, PostKBCategory
+
+parent_id = await client.create_kb_category(PostKBCategory(name="IT"))
+child_id = await client.create_kb_category(
+    PostKBCategory(name="Network", parent=IdNameRef(id=parent_id), is_recursive=True)
+)
+await client.update_kb_category(child_id, PatchKBCategory(comment="Moved"))
+category = await client.get_kb_category(child_id)
+print(category.completename, category.level)  # both server-managed
+
+await client.delete_kb_category(child_id, force=True)  # omit force to trash it
+await client.delete_kb_article(42, force=True)
+```
+
+## Gotchas
+
+- Assigning categories to an article is the only KB operation that needs the legacy v1 session, and it is not a v2 call at all: `set_kb_article_categories` issues a legacy `PUT KnowbaseItem/{article_id}` with the body `{"input": {"_categories": [ids]}}`. Every category CRUD call, every comment call and every revision call is pure v2.
+- When no v1 session is configured, that path raises a plain builtin `RuntimeError`, **not** a `GlpiError` -- `except GlpiError:` will not catch it. The message is `GLPI knowledge base category assignments require the legacy v1 session to be configured (set v1_base_url and v1_user_token).` The session is only built when *both* `v1_base_url` and `v1_user_token` are supplied; exactly one of the pair raises `GlpiValidationError` at client construction.
+- `create_kb_article` is not atomic and there is no rollback. If the v2 POST succeeds and the category fallback then fails, the article stays on the server: you get an error *and* an uncategorised article. The failure is a `RuntimeError` shaped `KB article 88 was created but assigning its categories failed: ...`, chaining the original as `__cause__` -- so the new id is recoverable only from the message text, and `except GlpiValidationError:` around a create catches nothing.
+- `update_kb_article` does not wrap the failure the way create does -- the raw error propagates (`GlpiValidationError` for a category reference with no `id`, `RuntimeError` for a missing v1 session, `GlpiStatusError` for a legacy non-success). The v2 field changes are already applied and are not reverted.
+- `categories=[]` means opposite things on create and update. On create it is skipped entirely: no v1 call, no v1 session needed. On update it *clears* every category, which is a legacy write and does need v1. Only `categories=None` (the default) is a no-op on both.
+- `categories` is still sent inside the v2 POST/PATCH body and GLPI silently ignores it; the body is never stripped. So a create-with-categories against a client with no v1 session yields an uncategorised article *and* an error, not a clean rejection -- and no code path persists a category through v2 alone.
+- **Every `search_*` helper in the library swallows 4xx and returns `[]`. This is a library-wide contract, not a KB peculiarity.** `_resource_list` checks the response status only when the caller passes a `failure_message`, and none of the seven searches -- `search_kb_articles`, `search_kb_categories`, `search_tickets`, `search_users`, `search_locations`, `search_entities`, `search_documents` -- passes one. A GLPI error body is not a JSON list, so it is coerced to `[]`. Every `list_*` and `get_*` helper does pass a `failure_message` and raises normally: here that is `list_kb_article_comments`, `list_kb_article_revisions`, `get_kb_article`, `get_kb_category` and `get_kb_article_revision` (`GlpiNotFoundError` on a 404). So an empty list from a search means "no matches" *or* "bad RSQL filter" *or* "403" *or* "this GLPI serves no `/Knowledgebase` routes at all" (they need High-Level API >= 2.2.0), indistinguishably; an empty list from a list helper is unambiguous. Never treat `[]` from a search as proof a record is absent before creating one.
+- `language` has two different mechanics in this family. On `search_kb_articles`/`search_kb_categories` it is a **query parameter**. On `list_kb_article_revisions`/`get_kb_article_revision` it is a **path segment** between the id and `Revision` (`Knowledgebase/Article/5/fr_FR/Revision`). `get_kb_article`, the comment helpers and every write helper take no `language` at all; they inherit the client-level value, sent as `Accept-Language` (default `en_GB`).
+- KB write models use `IdNameRef` for every foreign key -- `categories[]`, `entity`, `user`, `parent` -- not `IdRef`. Passing `IdRef(id=4)` raises a pydantic `ValidationError`. (`GetKBArticleComment.parent` is the one KB field genuinely typed `IdRef`, and it is read-only.)
+- Article `content`/`description` and revision `content` are Markdown on the Python side and HTML on the wire; the conversion is automatic, so never author HTML. Comment `comment` is a plain `str` with no conversion at all -- the inconsistency is real, not an omission here.
+- `force` on `delete_kb_article`, `delete_kb_category` and `delete_kb_article_comment` is keyword-only and is serialised into the JSON request **body** via the matching `Delete*` model, not sent as a query parameter. `force=True` deletes permanently; omitting it or passing `False` moves the record to the GLPI trash.
+- Revisions are read-only: there is no create/update/delete helper and no Post/Patch/Delete revision model. A revision appears as a side effect of updating an article. `get_kb_article_revision(article_id, revision)` takes the revision **number** (`GetKBArticleRevision.revision`), not the row `id` -- the two differ on the model.
+- `GetKBArticle.revisions` and `.translations` hold two *different* private ref classes (leading underscore, not exported from the package root). Read their attributes; never import them. The two field sets are not interchangeable: a `revisions` entry has `.id`, `.revision`, `.language`, `.date`, while a `translations` entry has `.id`, `.language`, `.name`. `revisions[0].name` raises `AttributeError` -- the models allow unknown keys from the server, but that does not synthesise an attribute that was never sent.

glpi_python_client-0.4.2/skills/glpi-plugin-fields/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: glpi-plugin-fields
+description: "Discover and read/write GLPI Fields-plugin custom fields with the synchronous glpi_python_client.GlpiClient or the asynchronous AsyncGlpiClient — list_plugin_fields_containers, list_plugin_fields_fields, list_item_plugin_field_rows, create_item_plugin_field_row, update_item_plugin_field_row, and the Ticket-only get_ticket_custom_fields/set_ticket_custom_fields. Use for GLPI custom fields, the Fields plugin, per-instance extra ticket attributes, or reading a ticket's custom-field values."
+license: MIT
+compatibility: "Requires Python 3.10+, glpi-python-client, the GLPI Fields plugin installed server-side, and a legacy v1 session (v1_base_url + v1_user_token) — every method in this family goes over the v1 API."
+metadata:
+  package: glpi-python-client
+  version: "0.4.1"
+---
+
+# GLPI Plugin Fields
+> The snippets below use `AsyncGlpiClient` (`async with` + `await`). Every method shown also exists on the synchronous `GlpiClient` with the same signature -- replace `async with` with `with`, drop the `await` keyword, and skip the surrounding `async def`/`asyncio.run` scaffolding.
+
+The GLPI `Fields` plugin adds user-defined custom fields to any itemtype: a *container* is a block of fields attached to one or more itemtypes, and each container stores one value row per item. None of it exists in the GLPI v2 contract, so all seven methods -- `list_plugin_fields_containers`, `list_plugin_fields_fields`, `list_item_plugin_field_rows`, `create_item_plugin_field_row`, `update_item_plugin_field_row`, and the Ticket-only `get_ticket_custom_fields`/`set_ticket_custom_fields` -- talk to the legacy v1 REST API. They are present on both `GlpiClient` and `AsyncGlpiClient` with identical signatures.
+
+Two constraints decide whether any of it works, so settle them first:
+
+- **Every one of the seven methods needs the legacy v1 session.** Build the client with `v1_base_url` *and* `v1_user_token` (or `GLPI_V1_BASE_URL`/`GLPI_V1_USER_TOKEN` for `from_env`). Without them the call raises a plain builtin `RuntimeError`, **not** a `GlpiError` -- `except GlpiError:` will not catch it. The message is `GLPI Fields plugin helpers require the legacy v1 session to be configured (set v1_base_url and v1_user_token).` Supplying exactly one of the pair raises `GlpiValidationError` at client construction instead.
+- **Discovery is mandatory, not advisory.** Container and field names are chosen by whoever configured the plugin on that instance, and the plugin itself is optional. There is nothing to hardcode: read `container.name` and `field.name` off the server and reuse them verbatim.
+
+```text
+list_plugin_fields_containers(itemtype) → list_plugin_fields_fields(container_id)
+    → list_item_plugin_field_rows(itemtype, items_id, container_name)
+    → create_item_plugin_field_row(...) / update_item_plugin_field_row(...)
+```
+
+The family takes two different `values` shapes and they are not interchangeable -- flat for the low-level row helpers, nested for the two Ticket helpers:
+
+```python
+# create_item_plugin_field_row / update_item_plugin_field_row -- FLAT,
+# one level, keyed by field.name:
+values = {"extrainfofield": "<p>x</p>"}
+
+# get_ticket_custom_fields / set_ticket_custom_fields -- NESTED,
+# outer key is container.name:
+values = {"extrainfo": {"extrainfofield": "<p>new</p>"}}
+```
+
+## Procedure
+
+1. Create a client from the `glpi-client-setup` skill, adding `v1_base_url` and `v1_user_token`.
+2. Discover containers with `list_plugin_fields_containers(itemtype="Ticket")`. `itemtype` is optional and filtered client-side. An uninstalled plugin does **not** return `[]`: it raises `GlpiStatusError` with `.status_code == 400` and `ERROR_RESOURCE_NOT_FOUND_NOR_COMMONDBTM` in `.response_text`. An installed-but-unused plugin returns `[]`.
+3. Discover fields with `list_plugin_fields_fields(container_id=container.id)`. `field.name` is the key you put in a `values` dict; `field.type` (`string`, `text`, `richtext`, `dropdown`, `yesno`, `date`, `datetime`, `number`, `url`, `header`) tells you the value format.
+4. Read the stored row with `list_item_plugin_field_rows(itemtype, items_id, container_name)` -- ordinary parameters, passable positionally or by keyword. It returns zero or one `GetPluginFieldsValueRow`; the values live in `row.extra_payload` and `row.id` is the `row_id` an update needs.
+5. Write with `update_item_plugin_field_row(itemtype=..., container_name=..., row_id=..., values=...)` when a row exists, otherwise `create_item_plugin_field_row(itemtype=..., items_id=..., container_id=..., container_name=..., values=..., entities_id=...)`, which returns the new row id. Both are keyword-only.
+6. On Tickets only, `get_ticket_custom_fields(ticket_id)` and `set_ticket_custom_fields(ticket_id, values)` fold steps 2-5 into one call each, using the nested mapping. For every other itemtype, drive steps 2-5 yourself.
+
+## Examples
+
+Discovery, including the branch that tells "plugin absent" apart from "plugin configured but empty":
+
+```python
+import asyncio
+
+from glpi_python_client import AsyncGlpiClient, GlpiStatusError
+
+# GLPI answers 400 with this marker when the itemtype in the URL is not a
+# known CommonDBTM subclass -- which is what an uninstalled plugin looks
+# like from the outside.
+PLUGIN_ABSENT = "ERROR_RESOURCE_NOT_FOUND_NOR_COMMONDBTM"
+
+
+async def main() -> None:
+    async with AsyncGlpiClient(
+        glpi_api_url="https://glpi.example.com/api.php/v2",
+        client_id="oauth-client-id",
+        client_secret="oauth-client-secret",
+        v1_base_url="https://glpi.example.com/api.php/v1",
+        v1_user_token="legacy-user-token",
+    ) as client:
+        try:
+            containers = await client.list_plugin_fields_containers(itemtype="Ticket")
+        except GlpiStatusError as exc:
+            if exc.status_code == 400 and PLUGIN_ABSENT in (exc.response_text or ""):
+                print("the GLPI Fields plugin is not installed on this instance")
+                return
+            raise
+
+        for container in containers:
+            if container.id is None or not container.name:
+                continue
+            # container.name is the internal key you reuse verbatim;
+            # container.label is the UI label and is never a valid key.
+            print(container.id, container.name, container.label, container.is_active)
+            fields = await client.list_plugin_fields_fields(container_id=container.id)
+            for field in fields:
+                print("   ", field.name, field.type, field.is_active, field.is_readonly)
+
+
+asyncio.run(main())
+```
+
+Read one ticket's custom fields. The result is the nested mapping, and a container with nothing saved is missing from it entirely:
+
+```python
+from glpi_python_client import AsyncGlpiClient
+
+
+async def ticket_note(client: AsyncGlpiClient, ticket_id: int) -> str | None:
+    """Return one ticket's `extrainfo.extrainfofield` value, if it has one."""
+    values = await client.get_ticket_custom_fields(ticket_id)
+    # {'extrainfo': {'extrainfofield': '<p>test</p>'}}
+
+    # Containers with no persisted row are ABSENT, not empty: `.get`, never [].
+    note = values.get("extrainfo", {}).get("extrainfofield")
+
+    # The inner dict is the row's extra_payload -- dynamic columns only, so
+    # it carries no row id. For that, drop to the low-level row listing:
+    rows = await client.list_item_plugin_field_rows("Ticket", ticket_id, "extrainfo")
+    if rows:
+        print(rows[0].id, rows[0].items_id, rows[0].extra_payload)
+    return note
+```
+
+Write to a ticket with the high-level upsert. Values go over the wire verbatim, so a `richtext` field takes raw HTML:
+
+```python
+from glpi_python_client import GlpiValidationError
+
+await client.set_ticket_custom_fields(
+    1234, {"extrainfo": {"extrainfofield": "<p>Handled by the NOC shift</p>"}}
+)
+# GET containers, GET fields, GET rows, then PUT {"input": {"id": 1, ...}}
+# -- or POST with items_id/itemtype/plugin_fields_containers_id if no row exists.
+
+await client.set_ticket_custom_fields(1234, {})  # empty mapping: zero HTTP calls
+
+# Container names are matched EXACT-CASE against container.name.
+try:
+    await client.set_ticket_custom_fields(1234, {"ExtraInfo": {"extrainfofield": "x"}})
+except GlpiValidationError as exc:
+    print(exc)  # Unknown plugin-fields container(s) for Ticket: ExtraInfo
+
+# The call is not atomic across containers, so write one per call when a
+# rejected field name must not leave the earlier container already written.
+payload = {
+    "extrainfo": {"extrainfofield": "<p>a</p>"},
+    "secondary": {"othercolumn": "b"},
+}
+for container_name, columns in payload.items():
+    await client.set_ticket_custom_fields(1234, {container_name: columns})
+```
+
+Upsert on any other itemtype, with the flat `values` dict and the low-level helpers:
+
+```python
+from glpi_python_client import AsyncGlpiClient
+
+
+async def upsert_plugin_field_row(
+    client: AsyncGlpiClient,
+    itemtype: str,               # "Computer", "Problem", "Change", ...
+    items_id: int,
+    container_id: int,           # container.id -- create needs it in the body
+    container_name: str,         # container.name -- it builds the URL itemtype
+    values: dict[str, object],   # FLAT: {field.name: value}
+) -> int:
+    """Update this container's row for one item, creating it when absent."""
+    # Positional is allowed here (ordinary parameters); the two writers
+    # below are keyword-only and raise TypeError if called positionally.
+    rows = await client.list_item_plugin_field_rows(itemtype, items_id, container_name)
+    if rows and rows[0].id is not None:
+        await client.update_item_plugin_field_row(
+            itemtype=itemtype,
+            container_name=container_name,
+            row_id=rows[0].id,
+            values=values,  # only these columns are touched
+        )
+        return rows[0].id
+    return await client.create_item_plugin_field_row(
+        itemtype=itemtype,
+        items_id=items_id,
+        container_id=container_id,
+        container_name=container_name,
+        values=values,
+        # `entities_id` is create-only and is omitted from the body unless
+        # you pass it, letting the server apply its default scope. Do NOT
+        # hardcode 0 here: 0 is not None, so it would pin every row you
+        # create to entity 0. Pass a real entity id only when you mean one.
+    )
+```
+
+## Gotchas
+
+- **The two `values` shapes are the main trap.** `create_item_plugin_field_row` and `update_item_plugin_field_row` take a **flat** `dict[str, object]` of field name to value -- `values={"extrainfofield": "<p>x</p>"}`. `get_ticket_custom_fields` returns, and `set_ticket_custom_fields` accepts, a **nested** `dict[str, dict[str, Any]]` keyed by container name -- `{"extrainfo": {"extrainfofield": "<p>new</p>"}}`. Passing the nested shape to the low-level create sends the inner dict as a column value; passing the flat shape to `set_ticket_custom_fields` makes field names look like container names and raises `GlpiValidationError: Unknown plugin-fields container(s) for Ticket: ...`.
+- `container_name` and `container_id` are not interchangeable, and `create_item_plugin_field_row` needs **both**. The name builds the URL itemtype, lowercased (`Ticket` + `extrainfo` gives `PluginFieldsTicketextrainfo`, and `Ticket/1234/PluginFieldsTicketextrainfo` for the row list). The id is a body column, `plugin_fields_containers_id`, and it is also what `list_plugin_fields_fields(container_id=...)` filters on. `update_item_plugin_field_row` needs only the name plus a `row_id`, which identifies the record on its own. `list_item_plugin_field_rows` needs only the name too, and has **no** `row_id` parameter -- its signature is exactly `(itemtype, items_id, container_name)`; it is what you call *to obtain* a `row_id`.
+- Container-name matching in `set_ticket_custom_fields` is **exact-case** against `container.name`, while the URL derivation lowercases. So `{"ExtraInfo": {...}}` raises `GlpiValidationError` when the container is actually named `extrainfo`, even though the derived URL would have been identical. Copy `container.name` verbatim from discovery; never retype it and never substitute `container.label`.
+- `set_ticket_custom_fields` is **not atomic across multiple containers**, despite a docstring claiming validation happens "before any write to keep the call atomic". Only the unknown-*container* check runs up front for the whole payload; the unknown-*field* check runs per container inside the write loop. With two containers where the second has a typo, the first is already written when the error raises. Write one container per call when you need all-or-nothing.
+- `get_ticket_custom_fields` returns **only `extra_payload`** -- every *undeclared* key of the row, not a curated list of the plugin's fields. So the row's `id`, `items_id`, `itemtype`, `plugin_fields_containers_id` and `entities_id` are absent (use `list_item_plugin_field_rows` when you need the `row_id`), and any other bookkeeping column the v1 server returns appears alongside real values. Intersect against `list_plugin_fields_fields` names if you need only declared fields.
+- A container that has never had a value saved for that ticket is **silently absent** from the `get_ticket_custom_fields` result -- you do not get `{"container": {}}`. Use `result.get(name, {})`, never `result[name]`. An empty overall dict is **ambiguous**: `get_ticket_custom_fields` builds its result by skipping every container with no persisted row, so `{}` comes back both when the instance declares no Ticket containers at all and when it declares several but this ticket has saved nothing in any of them. The return value cannot tell you which -- call `list_plugin_fields_containers(itemtype="Ticket")` if you need to know.
+- Both discovery listings fetch **one fixed page, `range=0-999`**, with no pagination and no server-side filtering. The `itemtype` and `container_id` narrowing happens client-side *after* that cap, so an instance with more than 1000 containers or field declarations silently loses the tail -- possibly including the container you are looking for.
+- Neither listing filters on `is_active`, so **disabled containers and disabled or read-only fields come back from discovery looking exactly like live ones**. `set_ticket_custom_fields` accepts a field whose `is_readonly` is `True`, because its guard only checks that the name is declared. Check `container.is_active`, `field.is_active` and `field.is_readonly` yourself.
+- Values are transmitted **verbatim -- there is no HTML/Markdown conversion on this path**, unlike ticket and KB article content. A `richtext` field takes raw HTML (`"<p>test</p>"`). Convert yourself if you want Markdown: `GlpiContentConverter` is not exported from the package root, import it from `glpi_python_client.content`.
+- The two convenience helpers are **Ticket-only** -- the itemtype is hardcoded. There is no `get_item_custom_fields` and no `set_item_custom_fields`. For Computer, Problem, Change and the rest, drive the generic row helpers.
+- Parameter-passing style is inconsistent across the family, and only one half of it is a rule. `list_item_plugin_field_rows(itemtype, items_id, container_name)` declares ordinary `POSITIONAL_OR_KEYWORD` parameters, so both `("Ticket", 1234, "extrainfo")` and `(itemtype="Ticket", items_id=1234, container_name="extrainfo")` are legal -- the examples above pass them positionally by choice, not by requirement. `create_item_plugin_field_row` and `update_item_plugin_field_row` are genuinely **keyword-only** (`*` in the signature): calling either writer positionally is a `TypeError`.
+- Error taxonomy on the write path: an unknown container name or an unknown field name raises `GlpiValidationError`; a container the server returned without an `id`, or a create whose v1 reply carries no numeric row id, raises `GlpiProtocolError`. Both inherit `ValueError`. A missing v1 session raises a plain `RuntimeError`, and a non-success v1 status raises `GlpiStatusError` (with `.status_code`, `.url` and `.response_text`).
+- `entities_id` exists on **create only**, and is left out of the body unless explicitly passed. `update_item_plugin_field_row` has no such parameter -- its body is exactly `{"input": {"id": row_id, **values}}`. `set_ticket_custom_fields` never passes it, so rows it creates take the GLPI server's default scope.
+- Cost is **linear and sequential**; there is no concurrent fan-out in this family. `get_ticket_custom_fields` costs one container list plus one row list per Ticket container. `set_ticket_custom_fields` costs one container list plus, per container in the payload, one field list, one row list and one write -- and it re-reads discovery on every call, with no caching. Cache the container and field listings yourself when writing many tickets in a loop.
+- `PostPluginFieldsValueRow` is exported at the package root but is **dead surface for callers**: no client method takes or returns it. `create_item_plugin_field_row` assembles the request body itself from a plain dict. Building this model and handing it to the client neither type-checks nor works.