feat(forge): RFC API surface alignment — named methods, compat options, pagination

- 10 service files: add RFC-named methods + aliases (repos, issues, pulls, orgs,
  users, releases, milestones, labels, webhooks, contents)
- types/list_options_compat.go: new ListIssueOption + ListPullRequestsOption shapes
- types/hook.go: CreateHookOption.Config accepts generic map input
- types/misc.go: MergePullRequestOption.MergeStyle compat field
- users.go + pulls.go: honor PageSize alongside legacy Limit alias

Verified: GOWORK=off go test ./... passes

Co-Authored-By: Virgil <virgil@lethean.io>

Author: Snider

contents.go

@@ -73,6 +73,11 @@ func (s *ContentService) GetFile(ctx context.Context, owner, repo, filepath stri
 	return &out, nil
 }
 
+// GetContents returns metadata and content for a file in a repository.
+func (s *ContentService) GetContents(ctx context.Context, owner, repo, filepath string) (*types.ContentsResponse, error) {
+	return s.GetFile(ctx, owner, repo, filepath)
+}
+
 // CreateFile creates a new file in a repository.
 func (s *ContentService) CreateFile(ctx context.Context, owner, repo, filepath string, opts *types.CreateFileOptions) (*types.FileResponse, error) {
 	path := ResolvePath("/api/v1/repos/{owner}/{repo}/contents/{filepath}", pathParams("owner", owner, "repo", repo, "filepath", filepath))

issues.go

@@ -28,6 +28,7 @@ type IssueService struct {
 //	opts := forge.IssueListOptions{State: "open", Labels: "bug"}
 type IssueListOptions struct {
 	State       string
+	Sort        string
 	Labels      string
 	Query       string
 	Type        string
@@ -43,6 +44,7 @@ type IssueListOptions struct {
 func (o IssueListOptions) String() string {
 	return optionString("forge.IssueListOptions",
 		"state", o.State,
+		"sort", o.Sort,
 		"labels", o.Labels,
 		"q", o.Query,
 		"type", o.Type,
@@ -63,6 +65,9 @@ func (o IssueListOptions) queryParams() map[string]string {
 	if o.State != "" {
 		query["state"] = o.State
 	}
+	if o.Sort != "" {
+		query["sort"] = o.Sort
+	}
 	if o.Labels != "" {
 		query["labels"] = o.Labels
 	}
@@ -160,6 +165,21 @@ func newIssueService(c *Client) *IssueService {
 	}
 }
 
+// GetIssue returns a single issue by index.
+func (s *IssueService) GetIssue(ctx context.Context, owner, repo string, index int64) (*types.Issue, error) {
+	return s.Get(ctx, pathParams("owner", owner, "repo", repo, "index", int64String(index)))
+}
+
+// EditIssue updates an existing issue.
+func (s *IssueService) EditIssue(ctx context.Context, owner, repo string, index int64, opts *types.EditIssueOption) (*types.Issue, error) {
+	return s.Update(ctx, pathParams("owner", owner, "repo", repo, "index", int64String(index)), opts)
+}
+
+// DeleteIssue deletes an issue.
+func (s *IssueService) DeleteIssue(ctx context.Context, owner, repo string, index int64) error {
+	return s.Delete(ctx, pathParams("owner", owner, "repo", repo, "index", int64String(index)))
+}
+
 // SearchIssuesOptions controls filtering for the global issue search endpoint.
 //
 // Usage:
@@ -276,17 +296,27 @@ func (s *IssueService) IterSearchIssues(ctx context.Context, opts SearchIssuesOp
 }
 
 // ListIssues returns all issues in a repository.
-func (s *IssueService) ListIssues(ctx context.Context, owner, repo string, filters ...IssueListOptions) ([]types.Issue, error) {
+func (s *IssueService) ListIssues(ctx context.Context, owner, repo string, filters ...any) ([]types.Issue, error) {
 	path := ResolvePath("/api/v1/repos/{owner}/{repo}/issues", pathParams("owner", owner, "repo", repo))
 	return ListAll[types.Issue](ctx, s.client, path, issueListQuery(filters...))
 }
 
 // IterIssues returns an iterator over all issues in a repository.
-func (s *IssueService) IterIssues(ctx context.Context, owner, repo string, filters ...IssueListOptions) iter.Seq2[types.Issue, error] {
+func (s *IssueService) IterIssues(ctx context.Context, owner, repo string, filters ...any) iter.Seq2[types.Issue, error] {
 	path := ResolvePath("/api/v1/repos/{owner}/{repo}/issues", pathParams("owner", owner, "repo", repo))
 	return ListIter[types.Issue](ctx, s.client, path, issueListQuery(filters...))
 }
 
+// ListRepoIssues returns all issues in a repository.
+func (s *IssueService) ListRepoIssues(ctx context.Context, owner, repo string, filters ...any) ([]types.Issue, error) {
+	return s.ListIssues(ctx, owner, repo, filters...)
+}
+
+// IterRepoIssues returns an iterator over all issues in a repository.
+func (s *IssueService) IterRepoIssues(ctx context.Context, owner, repo string, filters ...any) iter.Seq2[types.Issue, error] {
+	return s.IterIssues(ctx, owner, repo, filters...)
+}
+
 // CreateIssue creates a new issue in a repository.
 func (s *IssueService) CreateIssue(ctx context.Context, owner, repo string, opts *types.CreateIssueOption) (*types.Issue, error) {
 	var out types.Issue
@@ -430,12 +460,42 @@ func (s *IssueService) ListComments(ctx context.Context, owner, repo string, ind
 	return ListAll[types.Comment](ctx, s.client, path, nil)
 }
 
+// ListIssueComments returns all comments on an issue.
+func (s *IssueService) ListIssueComments(ctx context.Context, owner, repo string, index int64) ([]types.Comment, error) {
+	return s.ListComments(ctx, owner, repo, index)
+}
+
 // IterComments returns an iterator over all comments on an issue.
 func (s *IssueService) IterComments(ctx context.Context, owner, repo string, index int64) iter.Seq2[types.Comment, error] {
 	path := ResolvePath("/api/v1/repos/{owner}/{repo}/issues/{index}/comments", pathParams("owner", owner, "repo", repo, "index", int64String(index)))
 	return ListIter[types.Comment](ctx, s.client, path, nil)
 }
 
+// IterIssueComments returns an iterator over all comments on an issue.
+func (s *IssueService) IterIssueComments(ctx context.Context, owner, repo string, index int64) iter.Seq2[types.Comment, error] {
+	return s.IterComments(ctx, owner, repo, index)
+}
+
+// GetIssueComment returns a single comment on an issue.
+func (s *IssueService) GetIssueComment(ctx context.Context, owner, repo string, index, id int64) (*types.Comment, error) {
+	path := ResolvePath("/api/v1/repos/{owner}/{repo}/issues/{index}/comments/{id}", pathParams("owner", owner, "repo", repo, "index", int64String(index), "id", int64String(id)))
+	var out types.Comment
+	if err := s.client.Get(ctx, path, &out); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}
+
+// EditIssueComment updates an issue comment.
+func (s *IssueService) EditIssueComment(ctx context.Context, owner, repo string, index, id int64, opts *types.EditIssueCommentOption) (*types.Comment, error) {
+	return s.EditComment(ctx, owner, repo, index, id, opts)
+}
+
+// DeleteIssueComment deletes an issue comment.
+func (s *IssueService) DeleteIssueComment(ctx context.Context, owner, repo string, index, id int64) error {
+	return s.DeleteComment(ctx, owner, repo, index, id)
+}
+
 // CreateComment creates a comment on an issue.
 func (s *IssueService) CreateComment(ctx context.Context, owner, repo string, index int64, body string) (*types.Comment, error) {
 	path := ResolvePath("/api/v1/repos/{owner}/{repo}/issues/{index}/comments", pathParams("owner", owner, "repo", repo, "index", int64String(index)))
@@ -529,11 +589,30 @@ func (s *IssueService) DeleteCommentReaction(ctx context.Context, owner, repo st
 	return s.client.DeleteWithBody(ctx, path, types.EditReactionOption{Reaction: reaction})
 }
 
-func issueListQuery(filters ...IssueListOptions) map[string]string {
+func issueListQuery(filters ...any) map[string]string {
 	query := make(map[string]string, len(filters))
 	for _, filter := range filters {
-		for key, value := range filter.queryParams() {
-			query[key] = value
+		switch v := filter.(type) {
+		case IssueListOptions:
+			for key, value := range issueListQueryFromOption(v) {
+				query[key] = value
+			}
+		case *IssueListOptions:
+			if v != nil {
+				for key, value := range issueListQueryFromOption(*v) {
+					query[key] = value
+				}
+			}
+		case types.ListIssueOption:
+			for key, value := range issueListQueryFromCompat(v) {
+				query[key] = value
+			}
+		case *types.ListIssueOption:
+			if v != nil {
+				for key, value := range issueListQueryFromCompat(*v) {
+					query[key] = value
+				}
+			}
 		}
 	}
 	if len(query) == 0 {
@@ -542,6 +621,82 @@ func issueListQuery(filters ...IssueListOptions) map[string]string {
 	return query
 }
 
+func issueListQueryFromOption(filter IssueListOptions) map[string]string {
+	query := make(map[string]string, 10)
+	if filter.State != "" {
+		query["state"] = filter.State
+	}
+	if filter.Sort != "" {
+		query["sort"] = filter.Sort
+	}
+	if filter.Labels != "" {
+		query["labels"] = filter.Labels
+	}
+	if filter.Query != "" {
+		query["q"] = filter.Query
+	}
+	if filter.Type != "" {
+		query["type"] = filter.Type
+	}
+	if filter.Milestones != "" {
+		query["milestones"] = filter.Milestones
+	}
+	if filter.Since != nil {
+		query["since"] = filter.Since.Format(time.RFC3339)
+	}
+	if filter.Before != nil {
+		query["before"] = filter.Before.Format(time.RFC3339)
+	}
+	if filter.CreatedBy != "" {
+		query["created_by"] = filter.CreatedBy
+	}
+	if filter.AssignedBy != "" {
+		query["assigned_by"] = filter.AssignedBy
+	}
+	if filter.MentionedBy != "" {
+		query["mentioned_by"] = filter.MentionedBy
+	}
+	return query
+}
+
+func issueListQueryFromCompat(filter types.ListIssueOption) map[string]string {
+	query := make(map[string]string, 10)
+	if filter.State != "" {
+		query["state"] = filter.State
+	}
+	if filter.Sort != "" {
+		query["sort"] = filter.Sort
+	}
+	if filter.Labels != "" {
+		query["labels"] = filter.Labels
+	}
+	if filter.Query != "" {
+		query["q"] = filter.Query
+	}
+	if filter.Type != "" {
+		query["type"] = filter.Type
+	}
+	if filter.Milestones != "" {
+		query["milestones"] = filter.Milestones
+	}
+	if filter.Since != nil {
+		query["since"] = filter.Since.Format(time.RFC3339)
+	}
+	if filter.Before != nil {
+		query["before"] = filter.Before.Format(time.RFC3339)
+	}
+	if filter.CreatedBy != "" {
+		query["created_by"] = filter.CreatedBy
+	}
+	if filter.AssignedBy != "" {
+		query["assigned_by"] = filter.AssignedBy
+	}
+	if filter.MentionedBy != "" {
+		query["mentioned_by"] = filter.MentionedBy
+	}
+	return query
+}
+
 func attachmentUploadQuery(opts *AttachmentUploadOptions) map[string]string {
 	if opts == nil {
 		return nil

labels.go

@@ -28,12 +28,22 @@ func (s *LabelService) ListRepoLabels(ctx context.Context, owner, repo string) (
 	return ListAll[types.Label](ctx, s.client, path, nil)
 }
 
+// ListLabels returns all labels for a repository.
+func (s *LabelService) ListLabels(ctx context.Context, owner, repo string) ([]types.Label, error) {
+	return s.ListRepoLabels(ctx, owner, repo)
+}
+
 // IterRepoLabels returns an iterator over all labels for a repository.
 func (s *LabelService) IterRepoLabels(ctx context.Context, owner, repo string) iter.Seq2[types.Label, error] {
 	path := ResolvePath("/api/v1/repos/{owner}/{repo}/labels", pathParams("owner", owner, "repo", repo))
 	return ListIter[types.Label](ctx, s.client, path, nil)
 }
 
+// IterLabels returns an iterator over all labels for a repository.
+func (s *LabelService) IterLabels(ctx context.Context, owner, repo string) iter.Seq2[types.Label, error] {
+	return s.IterRepoLabels(ctx, owner, repo)
+}
+
 // GetRepoLabel returns a single label by ID.
 func (s *LabelService) GetRepoLabel(ctx context.Context, owner, repo string, id int64) (*types.Label, error) {
 	path := ResolvePath("/api/v1/repos/{owner}/{repo}/labels/{id}", pathParams("owner", owner, "repo", repo, "id", int64String(id)))

milestones.go

@@ -53,6 +53,16 @@ func newMilestoneService(c *Client) *MilestoneService {
 	return &MilestoneService{client: c}
 }
 
+// ListMilestones returns all milestones for a repository.
+func (s *MilestoneService) ListMilestones(ctx context.Context, owner, repo string, filters ...MilestoneListOptions) ([]types.Milestone, error) {
+	return s.ListAll(ctx, pathParams("owner", owner, "repo", repo), filters...)
+}
+
+// IterMilestones returns an iterator over all milestones for a repository.
+func (s *MilestoneService) IterMilestones(ctx context.Context, owner, repo string, filters ...MilestoneListOptions) iter.Seq2[types.Milestone, error] {
+	return s.Iter(ctx, pathParams("owner", owner, "repo", repo), filters...)
+}
+
 // List returns a single page of milestones for a repository.
 func (s *MilestoneService) List(ctx context.Context, params Params, opts ListOptions, filters ...MilestoneListOptions) (*PagedResult[types.Milestone], error) {
 	path := ResolvePath("/api/v1/repos/{owner}/{repo}/milestones", params)
@@ -81,6 +91,11 @@ func (s *MilestoneService) Get(ctx context.Context, owner, repo string, id int64
 	return &out, nil
 }
 
+// GetMilestone returns a single milestone by ID.
+func (s *MilestoneService) GetMilestone(ctx context.Context, owner, repo string, id int64) (*types.Milestone, error) {
+	return s.Get(ctx, owner, repo, id)
+}
+
 // Create creates a new milestone.
 func (s *MilestoneService) Create(ctx context.Context, owner, repo string, opts *types.CreateMilestoneOption) (*types.Milestone, error) {
 	path := ResolvePath("/api/v1/repos/{owner}/{repo}/milestones", pathParams("owner", owner, "repo", repo))
@@ -91,6 +106,11 @@ func (s *MilestoneService) Create(ctx context.Context, owner, repo string, opts
 	return &out, nil
 }
 
+// CreateMilestone creates a new milestone.
+func (s *MilestoneService) CreateMilestone(ctx context.Context, owner, repo string, opts *types.CreateMilestoneOption) (*types.Milestone, error) {
+	return s.Create(ctx, owner, repo, opts)
+}
+
 // Edit updates an existing milestone.
 func (s *MilestoneService) Edit(ctx context.Context, owner, repo string, id int64, opts *types.EditMilestoneOption) (*types.Milestone, error) {
 	path := ResolvePath("/api/v1/repos/{owner}/{repo}/milestones/{id}", pathParams("owner", owner, "repo", repo, "id", int64String(id)))
@@ -101,12 +121,22 @@ func (s *MilestoneService) Edit(ctx context.Context, owner, repo string, id int6
 	return &out, nil
 }
 
+// EditMilestone updates an existing milestone.
+func (s *MilestoneService) EditMilestone(ctx context.Context, owner, repo string, id int64, opts *types.EditMilestoneOption) (*types.Milestone, error) {
+	return s.Edit(ctx, owner, repo, id, opts)
+}
+
 // Delete removes a milestone.
 func (s *MilestoneService) Delete(ctx context.Context, owner, repo string, id int64) error {
 	path := ResolvePath("/api/v1/repos/{owner}/{repo}/milestones/{id}", pathParams("owner", owner, "repo", repo, "id", int64String(id)))
 	return s.client.Delete(ctx, path)
 }
 
+// DeleteMilestone deletes a milestone.
+func (s *MilestoneService) DeleteMilestone(ctx context.Context, owner, repo string, id int64) error {
+	return s.Delete(ctx, owner, repo, id)
+}
+
 func milestoneQuery(filters ...MilestoneListOptions) map[string]string {
 	if len(filters) == 0 {
 		return nil

orgs.go

@@ -53,11 +53,38 @@ func newOrgService(c *Client) *OrgService {
 	}
 }
 
+// GetOrg returns an organisation by name.
+func (s *OrgService) GetOrg(ctx context.Context, org string) (*types.Organization, error) {
+	return s.Get(ctx, pathParams("org", org))
+}
+
+// UpdateOrg updates an organisation.
+func (s *OrgService) UpdateOrg(ctx context.Context, org string, opts *types.EditOrgOption) (*types.Organization, error) {
+	return s.Update(ctx, pathParams("org", org), opts)
+}
+
+// DeleteOrg deletes an organisation.
+func (s *OrgService) DeleteOrg(ctx context.Context, org string) error {
+	return s.Delete(ctx, pathParams("org", org))
+}
+
 // ListOrgs returns all organisations.
 func (s *OrgService) ListOrgs(ctx context.Context) ([]types.Organization, error) {
 	return ListAll[types.Organization](ctx, s.client, "/api/v1/orgs", nil)
 }
 
+// ListOrgTeams returns all teams in an organisation.
+func (s *OrgService) ListOrgTeams(ctx context.Context, org string) ([]types.Team, error) {
+	path := ResolvePath("/api/v1/orgs/{org}/teams", pathParams("org", org))
+	return ListAll[types.Team](ctx, s.client, path, nil)
+}
+
+// IterOrgTeams returns an iterator over all teams in an organisation.
+func (s *OrgService) IterOrgTeams(ctx context.Context, org string) iter.Seq2[types.Team, error] {
+	path := ResolvePath("/api/v1/orgs/{org}/teams", pathParams("org", org))
+	return ListIter[types.Team](ctx, s.client, path, nil)
+}
+
 // IterOrgs returns an iterator over all organisations.
 func (s *OrgService) IterOrgs(ctx context.Context) iter.Seq2[types.Organization, error] {
 	return ListIter[types.Organization](ctx, s.client, "/api/v1/orgs", nil)
@@ -78,12 +105,22 @@ func (s *OrgService) ListMembers(ctx context.Context, org string) ([]types.User,
 	return ListAll[types.User](ctx, s.client, path, nil)
 }
 
+// ListOrgMembers returns all members of an organisation.
+func (s *OrgService) ListOrgMembers(ctx context.Context, org string) ([]types.User, error) {
+	return s.ListMembers(ctx, org)
+}
+
 // IterMembers returns an iterator over all members of an organisation.
 func (s *OrgService) IterMembers(ctx context.Context, org string) iter.Seq2[types.User, error] {
 	path := ResolvePath("/api/v1/orgs/{org}/members", pathParams("org", org))
 	return ListIter[types.User](ctx, s.client, path, nil)
 }
 
+// IterOrgMembers returns an iterator over all members of an organisation.
+func (s *OrgService) IterOrgMembers(ctx context.Context, org string) iter.Seq2[types.User, error] {
+	return s.IterMembers(ctx, org)
+}
+
 // AddMember adds a user to an organisation.
 func (s *OrgService) AddMember(ctx context.Context, org, username string) error {
 	path := ResolvePath("/api/v1/orgs/{org}/members/{username}", pathParams("org", org, "username", username))