feat: Add tags to a taxonomy (#2872)

Author: jesperhodge

package-lock.json

@@ -66,6 +66,7 @@
     "@openedx/paragon": "^23.5.0",
     "@redux-devtools/extension": "^3.3.0",
     "@reduxjs/toolkit": "2.11.2",
+    "@tanstack/react-table": "^8.21.3",
     "@tanstack/react-query": "5.90.21",
     "@tinymce/tinymce-react": "^6.0.0",
     "classnames": "2.5.1",

package.json

@@ -7,6 +7,7 @@ import {
   getTaxonomyListData,
   getTaxonomy,
   deleteTaxonomy,
+  getApiErrorMessage,
 } from './api';
 
 describe('taxonomy api calls', () => {
@@ -57,4 +58,82 @@ describe('taxonomy api calls', () => {
     // Restore the location object of window:
     window.location = origLocation;
   });
+
+  describe('getApiErrorMessage', () => {
+    it('returns first non-empty string when response data is an array', () => {
+      const err = {
+        response: {
+          data: ['', 'Array error message', 'Another message'],
+        },
+      };
+
+      expect(getApiErrorMessage(err)).toEqual('Array error message');
+    });
+
+    it('returns response data when it is a non-empty string', () => {
+      const err = {
+        response: {
+          data: 'String error message',
+        },
+      };
+
+      expect(getApiErrorMessage(err)).toEqual('String error message');
+    });
+
+    it('prefers object.error over detail and message fields', () => {
+      const err = {
+        response: {
+          data: {
+            error: 'Error field message',
+            detail: 'Detail field message',
+            message: 'Message field message',
+          },
+        },
+      };
+
+      expect(getApiErrorMessage(err)).toEqual('Error field message');
+    });
+
+    it('falls back to object.message then object.detail when needed', () => {
+      const messageErr = {
+        response: {
+          data: {
+            detail: 'Detail field message',
+            message: 'Message field message',
+          },
+        },
+      };
+      const detailErr = {
+        response: {
+          data: {
+            detail: 'Detail field message',
+          },
+        },
+      };
+
+      expect(getApiErrorMessage(messageErr)).toEqual('Message field message');
+      expect(getApiErrorMessage(detailErr)).toEqual('Detail field message');
+    });
+
+    it('falls back to top-level error message when response data is unparseable', () => {
+      const err = {
+        message: 'Top level error message',
+        response: {
+          data: [null, {}, '   '],
+        },
+      };
+
+      expect(getApiErrorMessage(err)).toEqual('Top level error message');
+    });
+
+    it('returns default message when no message is available', () => {
+      const err = {
+        response: {
+          data: null,
+        },
+      };
+
+      expect(getApiErrorMessage(err)).toEqual('Unknown error');
+    });
+  });
 });

src/taxonomy/data/api.test.ts

@@ -1,6 +1,8 @@
 import { camelCaseObject, getConfig } from '@edx/frontend-platform';
 import { getAuthenticatedHttpClient } from '@edx/frontend-platform/auth';
 import type { TaxonomyData, TaxonomyListData } from './types';
+import { MAX_TAXONOMY_ITEMS } from './constants';
+import messages from '../messages';
 
 const getApiBaseUrl = () => getConfig().STUDIO_BASE_URL;
 const getTaxonomiesV1Endpoint = () => new URL('api/content_tagging/v1/taxonomies/', getApiBaseUrl()).href;
@@ -53,19 +55,32 @@ export const apiUrls = {
   /** Get the URL for a Taxonomy */
   taxonomy: (taxonomyId: number) => makeUrl(`${taxonomyId}/`),
   /**
-   * Get the URL for listing the tags of a taxonomy
+   * Get the URL for listing the tags of a taxonomy.
+   * The max response size is 10,000 items, as set in the `MAX_TAXONOMY_ITEMS` constant.
+   * The backend does not support larger responses.
    * @param pageIndex Zero-indexed page number
    * @param pageSize How many tags per page to load
+   * @param fullDepth Whether to return max levels of child tags,
+   * with results limited by the MAX_TAXONOMY_ITEMS constant.
    */
-  tagList: (taxonomyId: number, pageIndex: number, pageSize: number) => makeUrl(`${taxonomyId}/tags/`, {
-    page: (pageIndex + 1), page_size: pageSize,
-  }),
+  tagList: (taxonomyId: number, {
+    pageIndex, pageSize, fullDepth, disablePagination,
+  }: { pageIndex: number | null; pageSize: number | null; fullDepth?: boolean; disablePagination?: boolean }) => {
+    if (disablePagination) {
+      return makeUrl(`${taxonomyId}/tags/`, { full_depth_threshold: fullDepth ? MAX_TAXONOMY_ITEMS : 0 });
+    }
+    return makeUrl(`${taxonomyId}/tags/`, {
+      page: (pageIndex ?? 0) + 1,
+      page_size: pageSize ?? 10,
+      full_depth_threshold: fullDepth ? MAX_TAXONOMY_ITEMS : 0,
+    });
+  },
   /**
    * Get _all_ tags below a given parent tag. This may be replaced with something more scalable in the future.
    */
   allSubtagsOf: (taxonomyId: number, parentTagValue: string) => makeUrl(`${taxonomyId}/tags/`, {
     // Load as deeply as we can
-    full_depth_threshold: 10000,
+    full_depth_threshold: MAX_TAXONOMY_ITEMS,
     parent_tag: parentTagValue,
   }),
   /** URL to create a new taxonomy from an import file. */
@@ -74,6 +89,7 @@ export const apiUrls = {
   tagsImport: (taxonomyId) => makeUrl(`${taxonomyId}/tags/import/`),
   /** URL to plan (preview what would happen) a taxonomy import */
   tagsPlanImport: (taxonomyId: number) => makeUrl(`${taxonomyId}/tags/import/plan/`),
+  createTag: (taxonomyId: number) => makeUrl(`${taxonomyId}/tags/`),
 } satisfies Record<string, (...args: any[]) => string>;
 
 /**
@@ -109,3 +125,46 @@ export async function getTaxonomy(taxonomyId: number): Promise<TaxonomyData> {
 export function getTaxonomyExportFile(taxonomyId: number, format: 'json' | 'csv'): void {
   window.location.href = apiUrls.exportTaxonomy(taxonomyId, format);
 }
+
+/**
+ * Extracts a human-readable error message from the API response.
+ *
+ * While most endpoints return an object (e.g., `{ error: "msg" }`), this specific
+ * backend call may return a raw array of strings: `["error1", "error2"]`. This function normalizes those
+ * edge cases by returning the first available error message.
+ * @param {unknown} err - The caught error object from the API.
+ * @param {Object} intl - The internationalization object to format default messages.
+ * @returns {string} The first detected error string or a default message if unparseable.
+ */
+export const getApiErrorMessage = (err: unknown, intl?: any): string => {
+  const error = err as { message?: string; response?: { data?: unknown } };
+  const responseData = error?.response?.data;
+
+  // `POST /api/content_tagging/v1/taxonomies/:id/tags/ with a duplicate tag name returns
+  // `["Tag with value 'abblue' already exists for taxonomy."]` as response body.
+  if (Array.isArray(responseData)) {
+    const firstMessage = responseData.find((item): item is string => typeof item === 'string' && item.trim().length > 0);
+    if (firstMessage) {
+      return firstMessage;
+    }
+  }
+
+  if (typeof responseData === 'string' && responseData.trim().length > 0) {
+    return responseData;
+  }
+
+  if (responseData && typeof responseData === 'object') {
+    const objectData = responseData as { error?: string; detail?: string; message?: string };
+    if (typeof objectData.error === 'string' && objectData.error.trim().length > 0) {
+      return objectData.error;
+    }
+    if (typeof objectData.message === 'string' && objectData.message.trim().length > 0) {
+      return objectData.message;
+    }
+    if (typeof objectData.detail === 'string' && objectData.detail.trim().length > 0) {
+      return objectData.detail;
+    }
+  }
+
+  return error?.message || (intl ? intl.formatMessage(messages.unknownErrorMessage) : 'Unknown error');
+};

src/taxonomy/data/api.ts

@@ -3,6 +3,7 @@ import React from 'react'; // Required to use JSX syntax without type errors
 
 import { initializeMockApp } from '@edx/frontend-platform';
 import { getAuthenticatedHttpClient } from '@edx/frontend-platform/auth';
+import { IntlProvider } from '@edx/frontend-platform/i18n';
 import { renderHook, waitFor } from '@testing-library/react';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 
@@ -11,6 +12,7 @@ import MockAdapter from 'axios-mock-adapter';
 import { apiUrls } from './api';
 
 import {
+  useCreateTag,
   useImportPlan,
   useImportTags,
   useImportNewTaxonomy,
@@ -28,7 +30,9 @@ const queryClient = new QueryClient({
 
 const wrapper = ({ children }) => (
   <QueryClientProvider client={queryClient}>
-    {children}
+    <IntlProvider locale="en">
+      {children}
+    </IntlProvider>
   </QueryClientProvider>
 );
 
@@ -105,4 +109,12 @@ describe('import taxonomy api calls', () => {
     expect(result.current.error).toEqual(Error('test error'));
     expect(axiosMock.history.put[0].url).toEqual(apiUrls.tagsPlanImport(1));
   });
+
+  it('should surface duplicate tag error returned as an array', async () => {
+    const duplicateError = "Tag with value 'ab' already exists for taxonomy.";
+    axiosMock.onPost(apiUrls.createTag(1)).reply(400, [duplicateError]);
+    const { result } = renderHook(() => useCreateTag(1), { wrapper });
+
+    await expect(result.current.mutateAsync({ value: 'ab' })).rejects.toEqual(Error(duplicateError));
+  });
 });

src/taxonomy/data/apiHooks.test.jsx

@@ -13,9 +13,10 @@
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import { camelCaseObject } from '@edx/frontend-platform';
 import { getAuthenticatedHttpClient } from '@edx/frontend-platform/auth';
-import { apiUrls, ALL_TAXONOMIES } from './api';
+import { apiUrls, ALL_TAXONOMIES, getApiErrorMessage } from './api';
 import * as api from './api';
 import type { QueryOptions, TagListData } from './types';
+import { useIntl } from '@edx/frontend-platform/i18n';
 
 // Query key patterns. Allows an easy way to clear all data related to a given taxonomy.
 // https://github.com/openedx/frontend-app-admin-portal/blob/2ba315d/docs/decisions/0006-tanstack-react-query.rst
@@ -139,7 +140,7 @@ export const useImportTags = () => {
         const { data } = await getAuthenticatedHttpClient().put(apiUrls.tagsImport(taxonomyId), formData);
         return camelCaseObject(data);
       } catch (err) {
-        throw new Error((err as any).response?.data?.error || (err as any).message);
+        throw new Error(getApiErrorMessage(err));
       }
     },
     onSuccess: (data) => {
@@ -170,7 +171,7 @@ export const useImportPlan = (taxonomyId: number, file: File | null) => useQuery
       const { data } = await getAuthenticatedHttpClient().put(apiUrls.tagsPlanImport(taxonomyId), formData);
       return data.plan as string;
     } catch (err) {
-      throw new Error((err as any).response?.data?.error || (err as any).message);
+      throw new Error(getApiErrorMessage(err));
     }
   },
   retry: false, // If there's an error, it's probably a real problem with the file. Don't try again several times!
@@ -180,13 +181,19 @@ export const useImportPlan = (taxonomyId: number, file: File | null) => useQuery
  * Use the list of tags in a taxonomy.
  */
 export const useTagListData = (taxonomyId: number, options: QueryOptions) => {
-  const { pageIndex, pageSize } = options;
+  const { pageIndex, pageSize, enabled = true, disablePagination = false } = options; // eslint-disable-line
   return useQuery({
-    queryKey: taxonomyQueryKeys.taxonomyTagListPage(taxonomyId, pageIndex, pageSize),
+    // queryKey: taxonomyQueryKeys.taxonomyTagListPage(taxonomyId, pageIndex, pageSize),
+    queryKey: taxonomyQueryKeys.taxonomyTagList(taxonomyId), // For now, ignore pagination in the query key.
     queryFn: async () => {
-      const { data } = await getAuthenticatedHttpClient().get(apiUrls.tagList(taxonomyId, pageIndex, pageSize));
+      const { data } = await getAuthenticatedHttpClient().get(
+        apiUrls.tagList(taxonomyId, {
+          pageIndex, pageSize, fullDepth: true, disablePagination,
+        }),
+      );
       return camelCaseObject(data) as TagListData;
     },
+    enabled,
   });
 };
 
@@ -202,3 +209,28 @@ export const useSubTags = (taxonomyId: number, parentTagValue: string) => useQue
     return camelCaseObject(response.data) as TagListData;
   },
 });
+
+export const useCreateTag = (taxonomyId: number) => {
+  const queryClient = useQueryClient();
+  const intl = useIntl();
+
+  return useMutation({
+    mutationFn: async ({ value, parentTagValue }: { value: string, parentTagValue?: string }) => {
+      try {
+        await getAuthenticatedHttpClient().post(
+          apiUrls.createTag(taxonomyId),
+          { tag: value, parent_tag_value: parentTagValue },
+        );
+      } catch (err) {
+        throw new Error(getApiErrorMessage(err, intl));
+      }
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: taxonomyQueryKeys.taxonomyTagList(taxonomyId),
+      });
+      // In the metadata, 'tagsCount' (and possibly other fields) will have changed:
+      queryClient.invalidateQueries({ queryKey: taxonomyQueryKeys.taxonomyMetadata(taxonomyId) });
+    },
+  });
+};

src/taxonomy/data/apiHooks.ts

@@ -0,0 +1,8 @@
+/**
+ * The maximum number of taxonomy items expected.
+ * Used to ensure that we load all nested subtags.
+ * This is set to the maximum value allowed by the backend.
+ * However, if the taxonomy size exceeds this value, the results
+ * will be incomplete because the backend only supports a taxonomy size of 10,000 items or fewer.
+ */
+export const MAX_TAXONOMY_ITEMS = 10000;

src/taxonomy/data/constants.ts

@@ -32,6 +32,8 @@ export interface TaxonomyListData {
 export interface QueryOptions {
   pageIndex: number;
   pageSize: number;
+  enabled?: boolean;
+  disablePagination?: boolean;
 }
 
 export interface TagData {
@@ -42,6 +44,8 @@ export interface TagData {
   id: number;
   parentValue: string | null;
   subTagsUrl: string | null;
+  canChangeTag?: boolean;
+  canDeleteTag?: boolean;
   /** Unique ID for this tag, also its display text */
   value: string;
   usageCount?: number;

src/taxonomy/data/types.ts

@@ -50,6 +50,10 @@ const messages = defineMessages({
     defaultMessage: 'Please keep this window open. We\'ll let you know when it\'s done.',
     description: 'Alert message when the taxonomy import is in progress.',
   },
+  unknownErrorMessage: {
+    id: 'course-authoring.taxonomy-list.error.unknown',
+    defaultMessage: 'Unknown error',
+  },
 });
 
 export default messages;