Epic 79/s2/#81 typed dto for all resources

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,
+    ) {
+    }
+}

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,
+    ) {
+    }
+}

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,
+    ) {
+    }
+}

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,
+    ) {
+    }
+}

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,
+    ) {
+    }
+}

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,
+    ) {
+    }
+}

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,
+    ) {
+    }
+}

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,
+    ) {
+    }
+}