add ticket context markdown and more exemples

Author: baraline

docs/user_guide.rst

@@ -436,6 +436,147 @@ timeline list calls concurrently and returns a single
    print(len(bundle.followups), len(bundle.tasks))
    print(len(bundle.solutions), len(bundle.documents))
 
+The context exposes :meth:`GlpiTicketContext.to_markdown` which renders
+the ticket header and every timeline event (followups, tasks,
+solutions, document links) as a single Markdown transcript. Events are
+ordered by ``timeline_position`` when set and otherwise by
+``date_creation``:
+
+.. code-block:: python
+
+   bundle = await client.get_ticket_context(ticket_id)
+   print(bundle.to_markdown())
+
+Focused Workflow Examples
+-------------------------
+
+The snippets below each exercise one focused workflow and end by
+rendering the resulting :class:`GlpiTicketContext` as Markdown. Every
+example is mirrored by an integration test in
+``integration_tests/test_integration.py`` (named
+``test_example_*``).
+
+Example 1 — Create a ticket and read it back
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from glpi_python_client import GlpiClient, PostTicket
+
+   async with GlpiClient.from_env() as client:
+       ticket_id = await client.create_ticket(
+           PostTicket(
+               name="Wi-Fi unreachable",
+               content="802.1X handshake fails on the 5 GHz radio.",
+           )
+       )
+       context = await client.get_ticket_context(ticket_id)
+       print(context.to_markdown())
+
+Expected Markdown (abridged)::
+
+   # Ticket #123 — Wi-Fi unreachable
+   - **Status**: New
+
+   802.1X handshake fails on the 5 GHz radio.
+
+Example 2 — Add a followup response
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from glpi_python_client import PostFollowup
+
+   await client.create_ticket_followup(
+       ticket_id,
+       PostFollowup(content="Reproduced on the lab laptop, capturing logs."),
+   )
+   context = await client.get_ticket_context(ticket_id)
+   print(context.to_markdown())
+
+Expected Markdown (abridged)::
+
+   # Ticket #123 — Wi-Fi unreachable
+
+   ## Followup #45
+   - **Created**: 2025-01-02T10:15:00+00:00
+
+   Reproduced on the lab laptop, capturing logs.
+
+Example 3 — Add a task with a duration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from glpi_python_client import PostTicketTask
+
+   await client.create_ticket_task(
+       ticket_id,
+       PostTicketTask(
+           content="On-site visit to swap the access point.",
+           duration=1800,
+       ),
+   )
+   context = await client.get_ticket_context(ticket_id)
+   print(context.to_markdown())
+
+Expected Markdown (abridged)::
+
+   ## Task #12
+   - **Duration**: 1800s
+
+   On-site visit to swap the access point.
+
+Example 4 — Close a ticket with a solution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+GLPI moves a ticket to the *Solved* status as soon as a solution is
+posted, so adding a solution is the supported way to change the ticket
+status from the v2 API.
+
+.. code-block:: python
+
+   from glpi_python_client import PostSolution
+
+   await client.create_ticket_solution(
+       ticket_id,
+       PostSolution(content="Replaced the access point firmware."),
+   )
+   context = await client.get_ticket_context(ticket_id)
+   print(context.to_markdown())
+
+Expected Markdown (abridged)::
+
+   # Ticket #123 — Wi-Fi unreachable
+   - **Status**: Solved
+
+   ## Solution #7
+
+   Replaced the access point firmware.
+
+Example 5 — Upload a document to an existing ticket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``upload_document`` accepts a ``ticket_id`` and links the new document
+to the timeline in a single call. The call requires the legacy v1
+session (``v1_base_url`` and ``v1_user_token``).
+
+.. code-block:: python
+
+   await client.upload_document(
+       filename="diagnostic.txt",
+       content=b"link layer ok\nradius timeout 3s\n",
+       mime_type="text/plain",
+       ticket_id=ticket_id,
+   )
+   context = await client.get_ticket_context(ticket_id)
+   print(context.to_markdown())
+
+Expected Markdown (abridged)::
+
+   ## Documents
+   - diagnostic.txt
+
 Reporting Helpers
 -----------------
 

glpi_python_client/models/custom_schema/_ticket_context.py

@@ -8,9 +8,13 @@
 
 from __future__ import annotations
 
+from datetime import datetime
+from typing import Any
+
 from pydantic import Field
 
 from glpi_python_client.models._base import GlpiModel
+from glpi_python_client.models.api_schema._common import IdNameRef
 from glpi_python_client.models.api_schema.assistance._ticket import GetTicket
 from glpi_python_client.models.api_schema.assistance.timeline._document import (
     GetTimelineDocument,
@@ -24,6 +28,44 @@
 from glpi_python_client.models.api_schema.assistance.timeline._task import (
     GetTicketTask,
 )
+from glpi_python_client.models.api_schema.enums import GlpiTimelinePosition
+
+_MAX_DATETIME = datetime.max
+
+
+def _ref_label(ref: IdNameRef | None) -> str | None:
+    """Return the human-readable label of one ``IdNameRef`` reference.
+
+    The helper prefers ``name`` (the GLPI display label) and falls back to
+    the numeric identifier when the server only returned the foreign key.
+    Returns ``None`` when the reference itself is missing so callers can
+    omit the field from the rendered Markdown.
+    """
+
+    if ref is None:
+        return None
+    if ref.name:
+        return ref.name
+    if ref.id is not None:
+        return f"#{ref.id}"
+    return None
+
+
+def _event_sort_key(event: Any) -> tuple[int, int, datetime]:
+    """Compute the sort key used to order timeline events for rendering.
+
+    Events with a meaningful ``timeline_position`` (a positive
+    :class:`GlpiTimelinePosition` member) come first in position order so
+    the rendered transcript matches the GLPI UI layout. The remaining
+    events fall back to ``date_creation``; events missing both attributes
+    are pushed to the end with a stable ordering.
+    """
+
+    position = getattr(event, "timeline_position", None)
+    fallback_date = getattr(event, "date_creation", None) or _MAX_DATETIME
+    if isinstance(position, GlpiTimelinePosition) and position.value > 0:
+        return (0, position.value, fallback_date)
+    return (1, 0, fallback_date)
 
 
 class GlpiTicketContext(GlpiModel):
@@ -49,5 +91,76 @@ class GlpiTicketContext(GlpiModel):
     solutions: list[GetSolution] = Field(default_factory=list)
     documents: list[GetTimelineDocument] = Field(default_factory=list)
 
+    def to_markdown(self) -> str:
+        """Render the ticket and its timeline as one Markdown transcript.
+
+        The header reports the ticket identifier, name, status, and body,
+        followed by every timeline event (followups, tasks, solutions)
+        sorted by ``timeline_position`` when set and otherwise by
+        ``date_creation``. Linked documents are appended at the end as a
+        bullet list because the timeline document link payload does not
+        carry a creation timestamp. Empty fields are omitted so the
+        output stays compact regardless of how complete the GLPI payload
+        is.
+
+        Returns
+        -------
+        str
+            Markdown transcript suitable for direct display or for
+            forwarding into a downstream Markdown renderer. The string
+            never ends with trailing whitespace.
+        """
+
+        lines: list[str] = []
+        ticket = self.ticket
+        ticket_label = ticket.name or "(unnamed ticket)"
+        if ticket.id is not None:
+            lines.append(f"# Ticket #{ticket.id} \u2014 {ticket_label}")
+        else:
+            lines.append(f"# Ticket \u2014 {ticket_label}")
+        status_label = _ref_label(ticket.status)
+        if status_label is not None:
+            lines.append(f"- **Status**: {status_label}")
+        if ticket.content:
+            lines.append("")
+            lines.append(ticket.content)
+
+        events: list[tuple[str, Any]] = []
+        events.extend(("Followup", item) for item in self.followups)
+        events.extend(("Task", item) for item in self.tasks)
+        events.extend(("Solution", item) for item in self.solutions)
+        events.sort(key=lambda pair: _event_sort_key(pair[1]))
+
+        for kind, event in events:
+            event_id = getattr(event, "id", None)
+            heading = f"## {kind} #{event_id}" if event_id is not None else f"## {kind}"
+            lines.append("")
+            lines.append(heading)
+            author_label = _ref_label(getattr(event, "user", None))
+            if author_label is not None:
+                lines.append(f"- **Author**: {author_label}")
+            created = getattr(event, "date_creation", None)
+            if created is not None:
+                lines.append(f"- **Created**: {created.isoformat()}")
+            duration = getattr(event, "duration", None)
+            if duration is not None:
+                lines.append(f"- **Duration**: {duration}s")
+            content = getattr(event, "content", None)
+            if content:
+                lines.append("")
+                lines.append(content)
+
+        if self.documents:
+            lines.append("")
+            lines.append("## Documents")
+            for document in self.documents:
+                identifier = document.documents_id or document.id
+                label = document.filepath or (
+                    f"document #{identifier}" if identifier is not None else "document"
+                )
+                lines.append(f"- {label}")
+
+        return "\n".join(lines).rstrip()
+
 
 __all__ = ["GlpiTicketContext"]