feat: enhance listMembers method with pagination and filtering options

src/api-client.ts

@@ -8,7 +8,8 @@
  */
 
 import type {
-	ProjectMember,
+	ListMembersOptions,
+	MemberPage,
 	ProjectSummary,
 	Task,
 	TaskFilters,
@@ -95,10 +96,20 @@ export class PluginApiClient {
 		);
 	}
 
-	/** List members of the current project. */
-	async listMembers(): Promise<ProjectMember[]> {
-		return this._get<ProjectMember[]>(
-			`${this.baseUrl}/projects/${this.projectId}/members`,
+	/**
+	 * One page of the current project's members (cursor-paginated). Pass
+	 * `ids` to look up specific members, `search` to filter by name; follow
+	 * `next_cursor` for further pages.
+	 */
+	async listMembers(opts: ListMembersOptions = {}): Promise<MemberPage> {
+		const params = new URLSearchParams();
+		if (opts.search) params.set("search", opts.search);
+		if (opts.ids?.length) params.set("ids", opts.ids.join(","));
+		if (opts.cursor) params.set("cursor", opts.cursor);
+		if (opts.pageSize) params.set("page_size", String(opts.pageSize));
+		const qs = params.toString();
+		return this._get<MemberPage>(
+			`${this.baseUrl}/projects/${this.projectId}/members${qs ? `?${qs}` : ""}`,
 		);
 	}
 

src/index.ts

@@ -33,6 +33,8 @@ export {
 // ── Types ─────────────────────────────────────────────────────────────────────
 export type {
 	PluginMeta,
+	ListMembersOptions,
+	MemberPage,
 	ProjectMember,
 	ProjectPermissions,
 	ProjectSummary,

src/types.ts

@@ -42,12 +42,35 @@ export interface ProjectSummary {
 
 // ── Members ───────────────────────────────────────────────────────────────────
 
-/** Project member entry returned by the members_list host function. */
+/** A project member as returned by the members list. */
 export interface ProjectMember {
 	id: string;
 	username: string;
 	full_name: string;
-	role_name: string;
+	/** The roles the member holds in the project. */
+	roles?: { id: string; name: string }[];
+}
+
+/** Filters for PluginApiClient.listMembers(). */
+export interface ListMembersOptions {
+	/** Words that must all appear in the member's username, name or handle. */
+	search?: string;
+	/** Only these members, by membership id or account id (at most 100). */
+	ids?: string[];
+	/** Cursor from a previous page's `next_cursor`. */
+	cursor?: string;
+	/** Page size, 1-100 (default 20). */
+	pageSize?: number;
+}
+
+/** One page of the members list, keyset-paginated by cursor. */
+export interface MemberPage {
+	items: ProjectMember[];
+	page_size: number;
+	/** Pass as `cursor` for the next page; null on the last page. */
+	next_cursor: string | null;
+	/** Members matching the filters across all pages. */
+	total_count: number;
 }
 
 /** Role-based permission flags available to plugin components. */