Add support for roles

[Echoloot]

Wanted to add a user to Zammad with certain role_ids but couldn't get the defined roles.

This adds support for /api/v1/roles and presents them in $client->role()

Summary by CodeRabbit

• New Features
  • Added support for retrieving and managing roles through the API, including role names, notes, and active status.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 5b51da03-03a4-442d-a46b-ebf1fd6c0d2c

📥 Commits

Reviewing files that changed from the base of the PR and between d0e941f and 4fd4280.

📒 Files selected for processing (4)

• src/Core/Repository/RepositoryRegistry.php
• src/Core/Traits/RepositoryAccessors.php
• src/Endpoints/Roles/RoleDTO.php
• src/Endpoints/Roles/RoleRepository.php

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds RoleDTO and RoleRepository for the roles endpoint. It registers the repository with the roles API path and RoleDTO, then adds a typed role() accessor that resolves the repository.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to 4fd42

The client adds typed access to documented role fields, with matching repository wiring. Available evidence shows no concrete incompatibility or actionable merge-blocking risk.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 4fd42

Role access reuses the client's existing connection and credentials, and no authorization bypass was demonstrated. However, the new repository exposes inherited write operations whose server-side permissions and retry guarantees remain unverified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The newly typed reachable surface includes role reads and mutation requests against the configured Zammad service. Effective exposure is bounded by the shared handler's credentials and server permissions, not by a new client identity. The number of affected tenants, role objects or downstream users cannot be established from this client repository.

Trust Boundaries and Controls

• observed — The role repository uses the client's shared handler. The standard factory supplies the configured Authorization header and disables redirects. Role registration adds no impersonation, credential substitution or separate authentication path.

Resilience and Maintainability Implications

• observed — Resource::save() processes the server response before clearing pending changes and marking a new record persisted. Resource::destroy() does not mark the wrapper terminal. These shared lifecycle semantics are unchanged; RoleRepository adds no role-specific reconciliation, concurrency control or recovery mechanism.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding support for roles and the roles endpoint.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}