feat: Contracts and Interfaces Architecture

src/Contracts/CommentManagerInterface.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Issue\Contracts;
+
+use ConduitUI\Issue\Data\Comment;
+use Illuminate\Support\Collection;
+
+/**
+ * Interface for managing issue comments.
+ *
+ * Provides operations for creating, updating, deleting,
+ * and retrieving comments on GitHub issues.
+ */
+interface CommentManagerInterface
+{
+    /**
+     * Create a new comment on an issue.
+     */
+    public function create(int $issueNumber, string $body): Comment;
+
+    /**
+     * Update an existing comment.
+     */
+    public function update(int $commentId, string $body): Comment;
+
+    /**
+     * Delete a comment.
+     */
+    public function delete(int $commentId): bool;
+
+    /**
+     * Get all comments for an issue.
+     *
+     * @return \Illuminate\Support\Collection<int, \ConduitUI\Issue\Data\Comment>
+     */
+    public function list(int $issueNumber): Collection;
+
+    /**
+     * Get a specific comment by ID.
+     */
+    public function get(int $commentId): Comment;
+}

src/Contracts/IssueBuilderInterface.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Issue\Contracts;
+
+use ConduitUI\Issue\Data\Issue;
+
+/**
+ * Interface for building GitHub issues.
+ *
+ * Provides a fluent interface for constructing issue data
+ * before creation, ensuring all required fields are set.
+ */
+interface IssueBuilderInterface
+{
+    /**
+     * Set the issue title.
+     */
+    public function title(string $title): self;
+
+    /**
+     * Set the issue body.
+     */
+    public function body(string $body): self;
+
+    /**
+     * Set the issue assignees.
+     *
+     * @param  array<string>  $assignees
+     */
+    public function assignees(array $assignees): self;
+
+    /**
+     * Add a single assignee.
+     */
+    public function assignee(string $assignee): self;
+
+    /**
+     * Set the issue labels.
+     *
+     * @param  array<string>  $labels
+     */
+    public function labels(array $labels): self;
+
+    /**
+     * Add a single label.
+     */
+    public function label(string $label): self;
+
+    /**
+     * Set the milestone number.
+     */
+    public function milestone(int $milestoneNumber): self;
+
+    /**
+     * Create the issue and return the Issue data object.
+     */
+    public function create(): Issue;
+
+    /**
+     * Get the raw data array without creating the issue.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(): array;
+}

src/Contracts/IssueManagerInterface.php

@@ -0,0 +1,114 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Issue\Contracts;
+
+use ConduitUI\Issue\Data\Comment;
+use ConduitUI\Issue\Data\Issue;
+use Illuminate\Support\Collection;
+
+/**
+ * Interface for managing GitHub issues.
+ *
+ * Provides high-level operations for CRUD, state management,
+ * labels, assignments, and related operations on issues.
+ */
+interface IssueManagerInterface
+{
+    /**
+     * Find an issue by number.
+     */
+    public function find(int $issueNumber): Issue;
+
+    /**
+     * Create a new query builder for issues.
+     */
+    public function query(): IssueQueryInterface;
+
+    /**
+     * Create a new issue.
+     *
+     * @param  array<string, mixed>  $data
+     */
+    public function create(array $data): Issue;
+
+    /**
+     * Update an existing issue.
+     *
+     * @param  array<string, mixed>  $data
+     */
+    public function update(int $issueNumber, array $data): Issue;
+
+    /**
+     * Close an issue with an optional comment.
+     */
+    public function close(int $issueNumber, ?string $comment = null): Issue;
+
+    /**
+     * Reopen a closed issue.
+     */
+    public function reopen(int $issueNumber): Issue;
+
+    /**
+     * Lock an issue with an optional reason.
+     */
+    public function lock(int $issueNumber, ?string $reason = null): bool;
+
+    /**
+     * Unlock an issue.
+     */
+    public function unlock(int $issueNumber): bool;
+
+    /**
+     * Add assignees to an issue.
+     *
+     * @param  array<string>  $assignees
+     */
+    public function addAssignees(int $issueNumber, array $assignees): Issue;
+
+    /**
+     * Remove assignees from an issue.
+     *
+     * @param  array<string>  $assignees
+     */
+    public function removeAssignees(int $issueNumber, array $assignees): Issue;
+
+    /**
+     * Add labels to an issue.
+     *
+     * @param  array<string>  $labels
+     */
+    public function addLabels(int $issueNumber, array $labels): Issue;
+
+    /**
+     * Remove labels from an issue.
+     *
+     * @param  array<string>  $labels
+     */
+    public function removeLabels(int $issueNumber, array $labels): Issue;
+
+    /**
+     * Replace all labels on an issue.
+     *
+     * @param  array<string>  $labels
+     */
+    public function replaceLabels(int $issueNumber, array $labels): Issue;
+
+    /**
+     * Remove all labels from an issue.
+     */
+    public function clearLabels(int $issueNumber): Issue;
+
+    /**
+     * Get all comments for an issue.
+     *
+     * @return \Illuminate\Support\Collection<int, \ConduitUI\Issue\Data\Comment>
+     */
+    public function comments(int $issueNumber): Collection;
+
+    /**
+     * Add a comment to an issue.
+     */
+    public function addComment(int $issueNumber, string $body): Comment;
+}

src/Contracts/IssueQueryInterface.php

@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Issue\Contracts;
+
+use ConduitUI\Issue\Data\Issue;
+use Illuminate\Support\Collection;
+
+/**
+ * Interface for querying and filtering GitHub issues.
+ *
+ * Provides a fluent interface for building complex issue queries with
+ * filtering, sorting, and pagination capabilities.
+ */
+interface IssueQueryInterface
+{
+    /**
+     * Filter issues by state (open, closed, or all).
+     */
+    public function state(string $state): self;
+
+    /**
+     * Filter issues by labels.
+     *
+     * @param  array<string>|string  $labels
+     */
+    public function labels(array|string $labels): self;
+
+    /**
+     * Filter issues by assignee username.
+     */
+    public function assignee(string $username): self;
+
+    /**
+     * Filter issues by creator username.
+     */
+    public function creator(string $username): self;
+
+    /**
+     * Filter issues mentioning a specific user.
+     */
+    public function mentioned(string $username): self;
+
+    /**
+     * Filter issues updated since a given date.
+     */
+    public function since(string|\DateTimeInterface $date): self;
+
+    /**
+     * Sort issues by created, updated, or comments.
+     */
+    public function sort(string $field): self;
+
+    /**
+     * Set sort direction (asc or desc).
+     */
+    public function direction(string $direction): self;
+
+    /**
+     * Set the number of results per page.
+     */
+    public function perPage(int $perPage): self;
+
+    /**
+     * Set the page number.
+     */
+    public function page(int $page): self;
+
+    /**
+     * Execute the query and return all matching issues.
+     *
+     * @return \Illuminate\Support\Collection<int, \ConduitUI\Issue\Data\Issue>
+     */
+    public function get(): Collection;
+
+    /**
+     * Execute the query and return the first matching issue.
+     */
+    public function first(): ?Issue;
+
+    /**
+     * Execute the query and return the count of matching issues.
+     */
+    public function count(): int;
+}

src/Contracts/IssuesFacadeInterface.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Issue\Contracts;
+
+/**
+ * Interface for the unified Issues facade.
+ *
+ * Provides high-level access to all manager interfaces through
+ * a single entry point, enabling clean and consistent API usage.
+ */
+interface IssuesFacadeInterface
+{
+    /**
+     * Get the issue manager for a repository.
+     */
+    public function issues(string $owner, string $repo): IssueManagerInterface;
+
+    /**
+     * Get the comment manager for a repository.
+     */
+    public function comments(string $owner, string $repo): CommentManagerInterface;
+
+    /**
+     * Get the label manager for a repository.
+     */
+    public function labels(string $owner, string $repo): LabelManagerInterface;
+
+    /**
+     * Get the reaction manager for a repository.
+     */
+    public function reactions(string $owner, string $repo): ReactionManagerInterface;
+
+    /**
+     * Get the milestone manager for a repository.
+     */
+    public function milestones(string $owner, string $repo): MilestoneManagerInterface;
+
+    /**
+     * Get the repository label manager for a repository.
+     */
+    public function repositoryLabels(string $owner, string $repo): RepositoryLabelManagerInterface;
+}