From d96405f8507fb503e1a481b1e7205d6862bce429 Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 1/9] feat(S2): Add UserDTO with typed fields (login, email,
 roles, active, etc.) and lenient fromArray parsing

EPIC-#79

#93
---
 src/Endpoints/Users/UserDTO.php | 49 +++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 src/Endpoints/Users/UserDTO.php

diff --git a/src/Endpoints/Users/UserDTO.php b/src/Endpoints/Users/UserDTO.php
new file mode 100644
index 0000000..a713c28
--- /dev/null
+++ b/src/Endpoints/Users/UserDTO.php
@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\Users;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad user resource (`/api/v1/users`).
+ *
+ * Users encompass both agents (Zammad staff) and customers (end-users). The
+ * distinction is made by the `role_id` field: agents have the "Agent" role,
+ * customers have the "Customer" role.
+ *
+ * Key fields:
+ *  - `login`           — Unique username; required for agents, optional for customers.
+ *  - `email`           — Primary email address; used for notifications and authentication.
+ *  - `firstname`/`lastname` — Display name components.
+ *  - `organization_id` — Links the user to an organization (customers only, typically).
+ *  - `role_id`         — Determines whether the user is an agent or a customer.
+ *
+ * All fields are nullable because the minimum required fields for creation
+ * differ between agents (need `login`) and customers (need `email`), and
+ * partial construction is common when building a DTO just to update one field.
+ */
+final readonly class UserDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public ?string $login = null,
+        public ?string $email = null,
+        public ?string $firstname = null,
+        public ?string $lastname = null,
+        public ?string $phone = null,
+        public ?int $organization_id = null,
+        public ?int $role_id = null,
+        public ?bool $active = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From 35ca3232ccac75dbd375cc27af39643e5ea599a6 Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 2/9] feat(S2): Add OrganizationDTO with typed fields (name,
 domain, members, note, etc.)

EPIC-#79

#94
---
 .../Organizations/OrganizationDTO.php         | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 src/Endpoints/Organizations/OrganizationDTO.php

diff --git a/src/Endpoints/Organizations/OrganizationDTO.php b/src/Endpoints/Organizations/OrganizationDTO.php
new file mode 100644
index 0000000..bcdc107
--- /dev/null
+++ b/src/Endpoints/Organizations/OrganizationDTO.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\Organizations;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad organization resource (`/api/v1/organizations`).
+ *
+ * Organizations group customer users under a shared company entity. A customer
+ * can belong to one primary organization; agents and organizations are separate
+ * (agents typically have no organization). Tickets created by a customer inherit
+ * the customer's organization, enabling company-wide ticket views.
+ *
+ * Server-assigned fields (`id`, `created_at`, `updated_at`) default to null and
+ * are populated by the API after `create()` or `find()`.
+ */
+final readonly class OrganizationDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public string $name,
+        public ?string $note = null,
+        public ?bool $active = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From 1aa0fd15964b8546c53cc9d57ab79579b898c9ad Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 3/9] feat(S2): Add GroupDTO with typed fields (name,
 signature_id, email_address_id, follow_up_*, active, etc.)

EPIC-#79

#95
---
 src/Endpoints/Groups/GroupDTO.php | 37 +++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 src/Endpoints/Groups/GroupDTO.php

diff --git a/src/Endpoints/Groups/GroupDTO.php b/src/Endpoints/Groups/GroupDTO.php
new file mode 100644
index 0000000..e231e0b
--- /dev/null
+++ b/src/Endpoints/Groups/GroupDTO.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\Groups;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad group resource (`/api/v1/groups`).
+ *
+ * Groups are routing containers for tickets. Every ticket belongs to exactly one
+ * group, which determines which agents can see and work on it. Groups also control
+ * SLA assignments, notification rules, and signature selection.
+ *
+ * Server-assigned fields (`id`, `created_at`, `updated_at`) default to null so
+ * the DTO can be constructed before persisting. After a `create()` or `find()` call
+ * the returned DTO will have these fields populated by the server.
+ */
+final readonly class GroupDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public string $name,
+        public ?string $note = null,
+        public ?bool $active = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From 232885a13337ae12977a2e31f2153dac334e94ee Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 4/9] feat(S2): Add TicketArticleDTO with typed fields
 (ticket_id, type, sender, subject, body, content_type, etc.)

EPIC-#79

#96
---
 .../TicketArticles/TicketArticleDTO.php       | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 src/Endpoints/TicketArticles/TicketArticleDTO.php

diff --git a/src/Endpoints/TicketArticles/TicketArticleDTO.php b/src/Endpoints/TicketArticles/TicketArticleDTO.php
new file mode 100644
index 0000000..e64b73b
--- /dev/null
+++ b/src/Endpoints/TicketArticles/TicketArticleDTO.php
@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\TicketArticles;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad ticket article resource (`/api/v1/ticket_articles`).
+ *
+ * A ticket article is a single message within a ticket's communication thread.
+ * It can represent an inbound email, an outbound reply, an internal note,
+ * a phone call log, or any other communication channel Zammad supports.
+ *
+ * Key fields:
+ *  - `ticket_id`    — The parent ticket this article belongs to.
+ *  - `type`         — Channel/type string (e.g. `'email'`, `'note'`, `'phone'`).
+ *  - `body`         — The content of the message.
+ *  - `content_type` — MIME type of the body (`'text/plain'` or `'text/html'`).
+ *
+ * Attachments are not represented as fields on the DTO; they must be downloaded
+ * separately via {@see \ZammadAPIClient\Endpoints\TicketArticles\TicketArticleRepository::getAttachmentContent()}.
+ *
+ * All fields are nullable because this DTO is also used for partial construction
+ * when creating new articles (not all fields are required by the API).
+ */
+final readonly class TicketArticleDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public ?int $ticket_id = null,
+        public ?string $type = null,
+        public ?string $body = null,
+        public ?string $content_type = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From dbaa93271a6d1fe006be842e6eb2b6e57fb9925c Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 5/9] feat(S2): Add TicketStateDTO with typed fields (name,
 state_type_id, active, note, etc.)

EPIC-#79

#97
---
 src/Endpoints/TicketStates/TicketStateDTO.php | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 src/Endpoints/TicketStates/TicketStateDTO.php

diff --git a/src/Endpoints/TicketStates/TicketStateDTO.php b/src/Endpoints/TicketStates/TicketStateDTO.php
new file mode 100644
index 0000000..52c0ded
--- /dev/null
+++ b/src/Endpoints/TicketStates/TicketStateDTO.php
@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\TicketStates;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad ticket state resource (`/api/v1/ticket_states`).
+ *
+ * Ticket states describe the current lifecycle stage of a ticket (e.g. "new",
+ * "open", "pending reminder", "closed"). Each state belongs to a state type
+ * (via `state_type_id`) that controls Zammad's internal behaviour, such as
+ * whether a ticket counts as open or closed for SLA calculations.
+ *
+ * Key fields:
+ *  - `name`          — Display label (e.g. `'open'`).
+ *  - `state_type_id` — References the internal state type; determines Zammad's
+ *                      automation behaviour for this state.
+ *
+ * Typically retrieved with `all()` to populate a state selector dropdown;
+ * rarely created or modified via the API.
+ */
+final readonly class TicketStateDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public string $name,
+        public ?int $state_type_id = null,
+        public ?string $note = null,
+        public ?bool $active = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From da89ccf11b026e4c82e2cc799ac60fe79a51e862 Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 6/9] feat(S2): Add TicketPriorityDTO with typed fields (name,
 default_create, ui_icon, ui_color, active, etc.)

EPIC-#79

#98
---
 .../TicketPriorities/TicketPriorityDTO.php    | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 src/Endpoints/TicketPriorities/TicketPriorityDTO.php

diff --git a/src/Endpoints/TicketPriorities/TicketPriorityDTO.php b/src/Endpoints/TicketPriorities/TicketPriorityDTO.php
new file mode 100644
index 0000000..b993900
--- /dev/null
+++ b/src/Endpoints/TicketPriorities/TicketPriorityDTO.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\TicketPriorities;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad ticket priority resource (`/api/v1/ticket_priorities`).
+ *
+ * Ticket priorities classify the urgency level of a ticket (e.g. "1 low",
+ * "2 normal", "3 high"). The default Zammad installation ships with three
+ * priorities; administrators can create additional ones via the API or UI.
+ *
+ * The `name` field is the display label; Zammad uses the numeric `id` when
+ * assigning a priority to a ticket via the `priority_id` field on
+ * {@see \ZammadAPIClient\Endpoints\Tickets\TicketDTO}.
+ */
+final readonly class TicketPriorityDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public string $name,
+        public ?string $note = null,
+        public ?bool $active = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From 464f1485f8fae93d102b3c29431d3f6163ff902c Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 7/9] feat(S2): Add TagDTO with typed fields (name, count,
 etc.)

EPIC-#79

#99
---
 src/Endpoints/Tags/TagDTO.php | 42 +++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 src/Endpoints/Tags/TagDTO.php

diff --git a/src/Endpoints/Tags/TagDTO.php b/src/Endpoints/Tags/TagDTO.php
new file mode 100644
index 0000000..3ec5222
--- /dev/null
+++ b/src/Endpoints/Tags/TagDTO.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\Tags;
+
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a single tag assignment on a Zammad object (`/api/v1/tags`).
+ *
+ * Tags in Zammad are not global labels by themselves; they exist as associations
+ * between a tag name (`value`) and a specific taggable object (identified by
+ * its type name `object` and numeric ID `o_id`).
+ *
+ * Field semantics:
+ *  - `value`  — The human-readable tag string (e.g. `'bug'`, `'urgent'`).
+ *  - `object` — Zammad object class name that the tag is attached to (e.g. `'Ticket'`).
+ *  - `o_id`   — The numeric ID of the specific object instance being tagged.
+ *
+ * All fields are nullable because the `/tag_search` autocomplete endpoint returns
+ * only `id` and `value` without `object` or `o_id`.
+ *
+ * Note: The `id` field here is the tag-assignment ID, not the tag label's ID in
+ * the Zammad tag list. Two identical tag strings on different tickets have
+ * different assignment IDs.
+ */
+final readonly class TagDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public ?int $id,
+        public ?string $object,
+        public ?int $o_id,
+        public ?string $value,
+    ) {
+    }
+}

From 6f7e0bc5a53eddef55d689b596a6e23a196292be Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 8/9] feat(S2): Add TextModuleDTO with typed fields (name,
 keywords, content, active, etc.)

EPIC-#79

#100
---
 src/Endpoints/TextModules/TextModuleDTO.php | 45 +++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 src/Endpoints/TextModules/TextModuleDTO.php

diff --git a/src/Endpoints/TextModules/TextModuleDTO.php b/src/Endpoints/TextModules/TextModuleDTO.php
new file mode 100644
index 0000000..86f4c0b
--- /dev/null
+++ b/src/Endpoints/TextModules/TextModuleDTO.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\TextModules;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad text module resource (`/api/v1/text_modules`).
+ *
+ * Text modules are canned-response templates that agents can search and insert
+ * into ticket replies. They support Zammad's variable interpolation syntax
+ * (e.g. `#{ticket.title}`, `#{customer.firstname}`) so content is personalised
+ * at insertion time.
+ *
+ * Key fields:
+ *  - `name`     — Display name shown in the search result list.
+ *  - `keywords` — Space-separated keywords that improve searchability without
+ *                 appearing in the inserted text.
+ *  - `content`  — The template body, optionally containing `#{...}` variables.
+ *
+ * Server-assigned fields (`id`, `created_at`, `updated_at`) default to null
+ * and are populated by the API after `create()` or `find()`.
+ */
+final readonly class TextModuleDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public string $name,
+        public ?string $keywords = null,
+        public ?string $content = null,
+        public ?string $note = null,
+        public ?bool $active = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From 55b71d2c86f8b6f49322aef64cfa2fc2f034fa2b Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 9/9] =?UTF-8?q?feat(S2):=20Complete=20typed=20DTOs=20for?=
 =?UTF-8?q?=20all=209=20resources=20=E2=80=94=20Ticket,=20User,=20Organiza?=
 =?UTF-8?q?tion,=20Group,=20TicketArticle,=20TicketState,=20TicketPriority?=
 =?UTF-8?q?,=20Tag,=20TextModule=20+=20TicketUpdateDTO?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

EPIC-#79

#81