feat: Implement DefineApplicationScopeStep with filtering and organization scope management

Author: bra-i-am

src/authz-module/data/api.test.ts

@@ -6,6 +6,8 @@ import {
   getLibrary,
   getPermissionsByRole,
   revokeUserRoles,
+  getScopes,
+  getOrganizations,
 } from './api';
 
 jest.mock('@edx/frontend-platform/auth', () => ({
@@ -171,3 +173,114 @@ describe('revokeUserRoles', () => {
     expect(result).toEqual(mockResponse);
   });
 });
+
+describe('getScopes', () => {
+  const mockScopesData = {
+    results: [{
+      externalKey: 'lib:testorg:testlib',
+      displayName: 'Test Library',
+      org: { id: 1, name: 'Test Org', shortName: 'testorg' },
+    }],
+    count: 1,
+    next: null,
+    previous: null,
+  };
+
+  it('builds URL with default page and pageSize when no optional params', async () => {
+    mockGet.mockResolvedValue({ data: mockScopesData });
+
+    const result = await getScopes({});
+
+    const calledUrl = new URL(mockGet.mock.calls[0][0]);
+    expect(calledUrl.searchParams.get('page')).toBe('1');
+    expect(calledUrl.searchParams.get('page_size')).toBe('10');
+    expect(calledUrl.searchParams.get('search')).toBeNull();
+    expect(calledUrl.searchParams.get('org')).toBeNull();
+    expect(calledUrl.searchParams.get('management_permission_only')).toBeNull();
+    expect(result).toEqual(mockScopesData);
+  });
+
+  it('appends search param when provided', async () => {
+    mockGet.mockResolvedValue({ data: mockScopesData });
+
+    await getScopes({ search: 'mylib' });
+
+    const calledUrl = new URL(mockGet.mock.calls[0][0]);
+    expect(calledUrl.searchParams.get('search')).toBe('mylib');
+  });
+
+  it('appends org param when provided', async () => {
+    mockGet.mockResolvedValue({ data: mockScopesData });
+
+    await getScopes({ org: 'testorg' });
+
+    const calledUrl = new URL(mockGet.mock.calls[0][0]);
+    expect(calledUrl.searchParams.get('org')).toBe('testorg');
+  });
+
+  it('appends management_permission_only when set to true', async () => {
+    mockGet.mockResolvedValue({ data: mockScopesData });
+
+    await getScopes({ managementPermissionOnly: true });
+
+    const calledUrl = new URL(mockGet.mock.calls[0][0]);
+    expect(calledUrl.searchParams.get('management_permission_only')).toBe('true');
+  });
+
+  it('uses provided page and pageSize', async () => {
+    mockGet.mockResolvedValue({ data: mockScopesData });
+
+    await getScopes({ page: 3, pageSize: 25 });
+
+    const calledUrl = new URL(mockGet.mock.calls[0][0]);
+    expect(calledUrl.searchParams.get('page')).toBe('3');
+    expect(calledUrl.searchParams.get('page_size')).toBe('25');
+  });
+
+  it('does not append managementPermissionOnly when false', async () => {
+    mockGet.mockResolvedValue({ data: mockScopesData });
+
+    await getScopes({ managementPermissionOnly: false });
+
+    const calledUrl = new URL(mockGet.mock.calls[0][0]);
+    expect(calledUrl.searchParams.get('management_permission_only')).toBeNull();
+  });
+});
+
+describe('getOrganizations', () => {
+  const mockOrg = {
+    id: 1,
+    name: 'Org One',
+    shortName: 'org1',
+    description: '',
+    logo: null,
+    active: true,
+  };
+
+  it('fetches from /api/authz/v1/orgs/ and returns results', async () => {
+    mockGet.mockResolvedValue({ data: { results: [mockOrg] } });
+
+    const result = await getOrganizations();
+
+    const calledUrl = new URL(mockGet.mock.calls[0][0]);
+    expect(calledUrl.pathname).toBe('/api/authz/v1/orgs/');
+    expect(result).toEqual([mockOrg]);
+  });
+
+  it('falls back to data directly when results is not present', async () => {
+    mockGet.mockResolvedValue({ data: [mockOrg] });
+
+    const result = await getOrganizations();
+
+    expect(result).toEqual([mockOrg]);
+  });
+
+  it('returns empty array when results is empty', async () => {
+    mockGet.mockResolvedValue({ data: { results: [] } });
+
+    const result = await getOrganizations();
+
+    expect(result).toEqual([]);
+    expect(mockGet).toHaveBeenCalled();
+  });
+});

src/authz-module/data/api.ts

@@ -120,6 +120,63 @@ export const getPermissionsByRole = async (scope: string): Promise<PermissionsBy
   return camelCaseObject(data.results);
 };
 
+export interface ScopeItem {
+  externalKey: string;
+  displayName: string;
+  org: { id: number; name: string; shortName: string } | null;
+  description?: string; // synthetic field used only for aggregate items created on the frontend
+}
+
+export interface GetScopesResponse {
+  results: ScopeItem[];
+  count: number;
+  next: string | null;
+  previous: string | null;
+}
+
+export interface GetScopesParams {
+  scopeType?: string;
+  search?: string;
+  org?: string;
+  page?: number;
+  pageSize?: number;
+  managementPermissionOnly?: boolean;
+}
+
+export interface OrganizationItem {
+  id: number;
+  name: string;
+  shortName: string;
+  description: string;
+  logo: string | null;
+  active: boolean;
+}
+
+export interface GetOrganizationsResponse {
+  results: OrganizationItem[];
+  count: number;
+  next: string | null;
+  previous: string | null;
+}
+
+export const getScopes = async (params: GetScopesParams): Promise<GetScopesResponse> => {
+  const url = new URL(getApiUrl('/api/authz/v1/scopes/'));
+  if (params.scopeType) { url.searchParams.set('scope_type', params.scopeType); }
+  if (params.search) { url.searchParams.set('search', params.search); }
+  if (params.org) { url.searchParams.set('org', params.org); }
+  if (params.managementPermissionOnly) { url.searchParams.set('management_permission_only', 'true'); }
+  url.searchParams.set('page', (params.page ?? 1).toString());
+  url.searchParams.set('page_size', (params.pageSize ?? 10).toString());
+  const { data } = await getAuthenticatedHttpClient().get(url);
+  return camelCaseObject(data);
+};
+
+export const getOrganizations = async (): Promise<OrganizationItem[]> => {
+  const url = new URL(getApiUrl('/api/authz/v1/orgs/'));
+  const { data } = await getAuthenticatedHttpClient().get(url);
+  return camelCaseObject(data.results ?? data);
+};
+
 export const revokeUserRoles = async (
   data: RevokeUserRolesRequest,
 ): Promise<DeleteRevokeUserRolesResponse> => {

src/authz-module/data/hooks.test.tsx

@@ -4,7 +4,7 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { getAuthenticatedHttpClient } from '@edx/frontend-platform/auth';
 import {
   useLibrary, usePermissionsByRole, useTeamMembers, useAssignTeamMembersRole, useRevokeUserRoles,
-  useValidateUsers,
+  useValidateUsers, useScopes, useOrganizations,
 } from './hooks';
 
 jest.mock('@edx/frontend-platform/auth', () => ({
@@ -290,6 +290,128 @@ describe('useValidateUsers', () => {
   });
 });
 
+describe('useScopes', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  const makeScopesResponse = (next: string | null = null) => ({
+    results: [{
+      externalKey: 'lib:testorg:testlib',
+      displayName: 'Test Library',
+      org: { id: 1, name: 'Test Org', slug: 'testorg' },
+    }],
+    count: 1,
+    next,
+    previous: null,
+  });
+
+  it('returns pages data on success', async () => {
+    getAuthenticatedHttpClient.mockReturnValue({
+      get: jest.fn().mockResolvedValue({ data: makeScopesResponse() }),
+    });
+
+    const { result } = renderHook(() => useScopes({}), { wrapper: createWrapper() });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data?.pages).toHaveLength(1);
+    expect(result.current.data?.pages[0].results).toHaveLength(1);
+  });
+
+  it('hasNextPage is false when next is null', async () => {
+    getAuthenticatedHttpClient.mockReturnValue({
+      get: jest.fn().mockResolvedValue({ data: makeScopesResponse(null) }),
+    });
+
+    const { result } = renderHook(() => useScopes({}), { wrapper: createWrapper() });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.hasNextPage).toBe(false);
+  });
+
+  it('hasNextPage is true when next URL has page param', async () => {
+    getAuthenticatedHttpClient.mockReturnValue({
+      get: jest.fn().mockResolvedValue({
+        data: makeScopesResponse('http://localhost:8000/api/authz/v1/scopes/?page=2'),
+      }),
+    });
+
+    const { result } = renderHook(() => useScopes({}), { wrapper: createWrapper() });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.hasNextPage).toBe(true);
+  });
+
+  it('hasNextPage is false when next URL has no page param', async () => {
+    getAuthenticatedHttpClient.mockReturnValue({
+      get: jest.fn().mockResolvedValue({
+        data: makeScopesResponse('http://localhost:8000/api/authz/v1/scopes/'),
+      }),
+    });
+
+    const { result } = renderHook(() => useScopes({}), { wrapper: createWrapper() });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.hasNextPage).toBe(false);
+  });
+
+  it('hasNextPage is false when next is an invalid URL', async () => {
+    getAuthenticatedHttpClient.mockReturnValue({
+      get: jest.fn().mockResolvedValue({
+        data: makeScopesResponse('not-a-valid-url'),
+      }),
+    });
+
+    const { result } = renderHook(() => useScopes({}), { wrapper: createWrapper() });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.hasNextPage).toBe(false);
+  });
+
+  it('handles error when API call fails', async () => {
+    getAuthenticatedHttpClient.mockReturnValue({
+      get: jest.fn().mockRejectedValue(new Error('Network error')),
+    });
+
+    const { result } = renderHook(() => useScopes({}), { wrapper: createWrapper() });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(result.current.error).toBeDefined();
+  });
+});
+
+describe('useOrganizations', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  const mockOrgs = [{
+    id: 1, name: 'Org One', shortName: 'org1', description: '', logo: null, active: true,
+  }];
+
+  it('returns organizations on success', async () => {
+    getAuthenticatedHttpClient.mockReturnValue({
+      get: jest.fn().mockResolvedValue({ data: { results: mockOrgs } }),
+    });
+
+    const { result } = renderHook(() => useOrganizations(), { wrapper: createWrapper() });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.data).toEqual(mockOrgs);
+  });
+
+  it('handles error when API fails', async () => {
+    getAuthenticatedHttpClient.mockReturnValue({
+      get: jest.fn().mockRejectedValue(new Error('Failed')),
+    });
+
+    const { result } = renderHook(() => useOrganizations(), { wrapper: createWrapper() });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+  });
+});
+
 describe('useRevokeUserRoles', () => {
   beforeEach(() => {
     jest.clearAllMocks();

src/authz-module/data/hooks.ts

@@ -1,12 +1,13 @@
 import {
-  useMutation, useQuery, useQueryClient, useSuspenseQuery,
+  useInfiniteQuery, useMutation, useQuery, useQueryClient, useSuspenseQuery,
 } from '@tanstack/react-query';
 import { appId } from '@src/constants';
 import { LibraryMetadata } from '@src/types';
 import {
-  assignTeamMembersRole, AssignTeamMembersRoleRequest, getLibrary, getPermissionsByRole, getTeamMembers,
-  GetTeamMembersResponse, PermissionsByRole, QuerySettings, revokeUserRoles, RevokeUserRolesRequest,
-  validateUsers, ValidateUsersRequest,
+  assignTeamMembersRole, AssignTeamMembersRoleRequest, getLibrary, getOrganizations,
+  getPermissionsByRole, getScopes, GetScopesParams, GetScopesResponse, getTeamMembers,
+  GetTeamMembersResponse, OrganizationItem, PermissionsByRole, QuerySettings, revokeUserRoles,
+  RevokeUserRolesRequest, validateUsers, ValidateUsersRequest,
 } from './api';
 
 const authzQueryKeys = {
@@ -106,6 +107,41 @@ export const useValidateUsers = () => useMutation({
   }) => validateUsers(data),
 });
 
+/**
+ * React Query hook to fetch a paginated, searchable list of scopes (courses or libraries).
+ * Uses infinite query to support infinite scroll.
+ *
+ * @param params - Filter params: contextType, search, org, pageSize
+ */
+export const useScopes = (params: Omit<GetScopesParams, 'page'>) => useInfiniteQuery<GetScopesResponse, Error>({
+  queryKey: [...authzQueryKeys.all, 'scopes', params],
+  queryFn: ({ pageParam }) => getScopes({ ...params, page: pageParam as number }),
+  getNextPageParam: (lastPage) => {
+    if (!lastPage.next) { return undefined; }
+    try {
+      const nextUrl = new URL(lastPage.next);
+      const page = nextUrl.searchParams.get('page');
+      return page ? parseInt(page, 10) : undefined;
+    } catch {
+      return undefined;
+    }
+  },
+  initialPageParam: 1,
+  staleTime: 1000 * 60 * 5,
+});
+
+/**
+ * React Query hook to fetch the list of organizations for a given context type.
+ * Used to populate the Organization filter dropdown in the scope selector.
+ *
+ * @param contextType - 'course' | 'library'
+ */
+export const useOrganizations = () => useQuery<OrganizationItem[], Error>({
+  queryKey: [...authzQueryKeys.all, 'organizations'],
+  queryFn: () => getOrganizations(),
+  staleTime: 1000 * 60 * 30,
+});
+
 /**
  * React Query hook to remove roles for a specific team member within a scope.
  *