richie-education 2.25.0-b2.dev32 → 2.25.0-b2.dev35

package/js/pages/TeacherDashboardContractsLayout/hooks/useCheckContractArchiveExists/index.tsx

@@ -0,0 +1,73 @@
+import { useEffect, useRef, useState } from 'react';
+import useContractArchive from 'hooks/useContractArchive';
+import { CONTRACT_DOWNLOAD_SETTINGS } from 'settings';
+import { Nullable } from 'types/utils';
+import { getStoredContractArchiveId } from '../useDownloadContractArchive/contractArchiveLocalStorage';
+
+export interface UseCheckContractArchiveExistsProps {
+  enable: boolean;
+}
+
+const useCheckContractArchiveExist = (
+  { enable }: UseCheckContractArchiveExistsProps = { enable: true },
+) => {
+  // Contract's archive api interface
+  const {
+    methods: { check: checkArchiveExist },
+  } = useContractArchive();
+
+  // Store if the contract's archive exists or not on the server
+  // stay null until fetched
+  const [isContractArchiveExists, setIsContractArchiveExists] = useState<Nullable<boolean>>(null);
+
+  const timeoutRef = useRef<NodeJS.Timeout>();
+
+  // This method will check if the archive exists on the server
+  // option.polling === true will recursivly poll archive existence
+  const checkArchiveExists = async (
+    archiveId: string,
+    options: { polling: boolean } = { polling: true },
+  ) => {
+    clearTimeout(timeoutRef.current);
+    timeoutRef.current = undefined;
+
+    const isExists = await checkArchiveExist(archiveId);
+    setIsContractArchiveExists(isExists);
+
+    if (!options.polling) {
+      return;
+    }
+
+    if (!isExists) {
+      timeoutRef.current = setTimeout(
+        () => checkArchiveExists(archiveId),
+        CONTRACT_DOWNLOAD_SETTINGS.pollInterval,
+      );
+    }
+  };
+
+  // This effect will initialize isContractArchiveExists value
+  useEffect(() => {
+    const storedContractArchiveId = getStoredContractArchiveId();
+    if (enable && storedContractArchiveId) {
+      checkArchiveExists(storedContractArchiveId, { polling: false });
+    } else {
+      setIsContractArchiveExists(false);
+    }
+  }, [enable]);
+
+  // Be sure to clear any timeout before unmouting the hook.
+  useEffect(() => {
+    return () => {
+      clearTimeout(timeoutRef.current);
+    };
+  }, []);
+
+  return {
+    isPolling: !!timeoutRef.current,
+    isContractArchiveExists,
+    checkArchiveExists,
+  };
+};
+
+export default useCheckContractArchiveExist;

package/js/pages/TeacherDashboardContractsLayout/hooks/useDownloadContractArchive/contractArchiveLocalStorage.spec.ts

@@ -0,0 +1,85 @@
+import { faker } from '@faker-js/faker';
+import { CONTRACT_DOWNLOAD_SETTINGS } from 'settings';
+import {
+  getStoredContractArchiveId,
+  isStoredContractArchiveIdExpired,
+  storeContractArchiveId,
+  unstoreContractArchiveId,
+} from './contractArchiveLocalStorage';
+
+describe('contractArchiveLocalStorage', () => {
+  afterEach(() => {
+    unstoreContractArchiveId();
+  });
+
+  it('should store and unstore contractArchiveId and creation date in localStorage', () => {
+    expect(
+      localStorage.getItem(CONTRACT_DOWNLOAD_SETTINGS.contractArchiveLocalStorageKey),
+    ).toBeNull();
+
+    const contractArchiveId = faker.string.uuid();
+    storeContractArchiveId(contractArchiveId);
+    expect(localStorage.getItem(CONTRACT_DOWNLOAD_SETTINGS.contractArchiveLocalStorageKey)).toMatch(
+      new RegExp(`[0-9]+::${contractArchiveId}`),
+    );
+
+    unstoreContractArchiveId();
+    expect(
+      localStorage.getItem(CONTRACT_DOWNLOAD_SETTINGS.contractArchiveLocalStorageKey),
+    ).toBeNull();
+  });
+
+  it('should retrieve contractArchiveId from localStorage', () => {
+    const contractArchiveId = faker.string.uuid();
+    storeContractArchiveId(contractArchiveId);
+
+    const retrievedcontractArchiveId = getStoredContractArchiveId();
+    expect(retrievedcontractArchiveId).toBe(contractArchiveId);
+  });
+
+  it.each([
+    {
+      label: 'outdated creation date in the past',
+      now: Date.now(),
+      storageCreationTime:
+        Date.now() - CONTRACT_DOWNLOAD_SETTINGS.contractArchiveLocalVaklidityDurationMs * 2,
+    },
+    {
+      label: 'outdated creation date in the future',
+      now: Date.now(),
+      storageCreationTime:
+        Date.now() + CONTRACT_DOWNLOAD_SETTINGS.contractArchiveLocalVaklidityDurationMs * 2,
+    },
+  ])(
+    'isStoredContractArchiveIdExpired should be true for $label',
+    ({ now, storageCreationTime }) => {
+      jest.useFakeTimers();
+      jest.setSystemTime(new Date(storageCreationTime));
+      const contractArchiveId = faker.string.uuid();
+      storeContractArchiveId(contractArchiveId);
+
+      jest.setSystemTime(new Date(now));
+      expect(isStoredContractArchiveIdExpired()).toBe(true);
+
+      jest.runOnlyPendingTimers();
+      jest.useRealTimers();
+    },
+  );
+
+  it("isStoredContractArchiveIdExpired should be true false storage isn't expired", () => {
+    const now = Date.now();
+    const validCreationTime =
+      now - CONTRACT_DOWNLOAD_SETTINGS.contractArchiveLocalVaklidityDurationMs / 2;
+
+    jest.useFakeTimers();
+    jest.setSystemTime(new Date(validCreationTime));
+    const contractArchiveId = faker.string.uuid();
+    storeContractArchiveId(contractArchiveId);
+
+    jest.setSystemTime(new Date(now));
+    expect(isStoredContractArchiveIdExpired()).toBe(false);
+
+    jest.runOnlyPendingTimers();
+    jest.useRealTimers();
+  });
+});

package/js/pages/TeacherDashboardContractsLayout/hooks/useDownloadContractArchive/contractArchiveLocalStorage.ts

@@ -0,0 +1,50 @@
+import { CONTRACT_DOWNLOAD_SETTINGS } from 'settings';
+
+const generateLocalStorageId = (contractArchiveId: string) => {
+  return `${Date.now()}::${contractArchiveId}`;
+};
+
+const storeContractArchiveId = (contractArchiveId: string) => {
+  localStorage.setItem(
+    CONTRACT_DOWNLOAD_SETTINGS.contractArchiveLocalStorageKey,
+    generateLocalStorageId(contractArchiveId),
+  );
+};
+
+const unstoreContractArchiveId = () => {
+  localStorage.removeItem(CONTRACT_DOWNLOAD_SETTINGS.contractArchiveLocalStorageKey);
+};
+
+const getStoredContractArchiveId = () => {
+  const value = localStorage.getItem(CONTRACT_DOWNLOAD_SETTINGS.contractArchiveLocalStorageKey);
+  if (value === null) {
+    return value;
+  }
+
+  const [, contractArchiveId] = value.split('::');
+  return contractArchiveId;
+};
+
+const isStoredContractArchiveIdExpired = () => {
+  const value = localStorage.getItem(CONTRACT_DOWNLOAD_SETTINGS.contractArchiveLocalStorageKey);
+  if (value === null) {
+    return false;
+  }
+  const [creationTimestamp] = value.split('::');
+
+  const bounds: number[] = [Date.now(), parseInt(creationTimestamp, 10)];
+  // reverse bounds when computer time change.
+  if (bounds[0] > bounds[1]) {
+    bounds.reverse();
+  }
+
+  const [begin, end] = bounds;
+  return end - begin > CONTRACT_DOWNLOAD_SETTINGS.contractArchiveLocalVaklidityDurationMs;
+};
+
+export {
+  storeContractArchiveId,
+  unstoreContractArchiveId,
+  getStoredContractArchiveId,
+  isStoredContractArchiveIdExpired,
+};

package/js/pages/TeacherDashboardContractsLayout/hooks/useDownloadContractArchive/index.spec.tsx

@@ -0,0 +1,266 @@
+import { faker } from '@faker-js/faker';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { IntlProvider } from 'react-intl';
+import { PropsWithChildren } from 'react';
+import { RichieContextFactory as mockRichieContextFactory } from 'utils/test/factories/richie';
+import JoanieApiProvider from 'contexts/JoanieApiContext';
+import { CONTRACT_DOWNLOAD_SETTINGS } from 'settings';
+import {
+  getStoredContractArchiveId,
+  storeContractArchiveId,
+  unstoreContractArchiveId,
+} from './contractArchiveLocalStorage';
+import useDownloadContractArchive, { ContractDownloadStatus } from '.';
+
+jest.mock('settings', () => ({
+  ...jest.requireActual('settings'),
+  CONTRACT_DOWNLOAD_SETTINGS: {
+    ...jest.requireActual('settings').CONTRACT_DOWNLOAD_SETTINGS,
+    pollInterval: 100,
+  },
+}));
+
+jest.mock('utils/context', () => ({
+  __esModule: true,
+  default: mockRichieContextFactory({
+    authentication: { backend: 'fonzie', endpoint: 'https://auth.test' },
+    joanie_backend: { endpoint: 'https://joanie.test' },
+  }).one(),
+}));
+
+const mockCheckArchive = jest.fn();
+const mockCreateArchive = jest.fn();
+const mockGetArchive = jest.fn();
+jest.mock('hooks/useContractArchive', () => ({
+  __esModule: true,
+  default: () => ({
+    methods: { get: mockGetArchive, create: mockCreateArchive, check: mockCheckArchive },
+  }),
+}));
+
+let mockHasContractToDownload: boolean;
+jest.mock('pages/TeacherDashboardContractsLayout/hooks/useHasContractToDownload/index.tsx', () => ({
+  __esModule: true,
+  default: () => mockHasContractToDownload,
+}));
+
+describe('useDownloadContractArchive', () => {
+  let organizationId: string;
+  const Wrapper = ({ children }: PropsWithChildren) => {
+    return (
+      <IntlProvider locale="en">
+        <JoanieApiProvider>{children}</JoanieApiProvider>
+      </IntlProvider>
+    );
+  };
+
+  afterEach(() => {
+    jest.resetAllMocks();
+    unstoreContractArchiveId();
+  });
+
+  describe('with no contract available for download', () => {
+    beforeEach(() => {
+      organizationId = faker.string.uuid();
+      mockHasContractToDownload = false;
+    });
+
+    it('should return IDLE status when no contractArchiveId is stored', async () => {
+      const { result } = renderHook(() => useDownloadContractArchive({ organizationId }), {
+        wrapper: Wrapper,
+      });
+      expect(result.current.status).toBe(ContractDownloadStatus.IDLE);
+
+      // no api call should have been done.
+      expect(mockCheckArchive).not.toHaveBeenCalled();
+      expect(mockGetArchive).not.toHaveBeenCalled();
+      expect(mockCreateArchive).not.toHaveBeenCalled();
+    });
+
+    it('should return IDLE status when contractArchiveId is stored', async () => {
+      const contractArchiveId = faker.string.uuid();
+      storeContractArchiveId(contractArchiveId);
+
+      const { result } = renderHook(() => useDownloadContractArchive({ organizationId }), {
+        wrapper: Wrapper,
+      });
+
+      expect(result.current.status).toBe(ContractDownloadStatus.IDLE);
+
+      // no api call should have been done.
+      expect(mockCheckArchive).not.toHaveBeenCalled();
+      expect(mockGetArchive).not.toHaveBeenCalled();
+      expect(mockCreateArchive).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('with contracts available for download', () => {
+    beforeEach(() => {
+      organizationId = faker.string.uuid();
+      mockHasContractToDownload = true;
+    });
+
+    it('should return IDLE status when no contractArchiveId is stored', async () => {
+      const { result } = renderHook(() => useDownloadContractArchive({ organizationId }), {
+        wrapper: Wrapper,
+      });
+
+      // ensure that initial effects are done
+      expect(result.current.status).toBe(ContractDownloadStatus.IDLE);
+
+      // no api call should have been done.
+      expect(mockCheckArchive).not.toHaveBeenCalled();
+      expect(mockGetArchive).not.toHaveBeenCalled();
+      expect(mockCreateArchive).not.toHaveBeenCalled();
+    });
+
+    it('should return PENDING status when a contractArchiveId is stored', async () => {
+      const contractArchiveId = faker.string.uuid();
+      storeContractArchiveId(contractArchiveId);
+      mockCheckArchive.mockResolvedValue(false);
+
+      const { result } = renderHook(() => useDownloadContractArchive({ organizationId }), {
+        wrapper: Wrapper,
+      });
+
+      await waitFor(() => {
+        expect(result.current.status).toBe(ContractDownloadStatus.PENDING);
+      });
+
+      expect(mockCheckArchive).toHaveBeenCalledTimes(1);
+      expect(mockGetArchive).not.toHaveBeenCalled();
+      expect(mockCreateArchive).not.toHaveBeenCalled();
+    });
+
+    it('should return READY status when a contractArchiveId is stored and it exists on the server', async () => {
+      const contractArchiveId = faker.string.uuid();
+      storeContractArchiveId(contractArchiveId);
+      mockCheckArchive.mockResolvedValue(true);
+
+      const { result } = renderHook(() => useDownloadContractArchive({ organizationId }), {
+        wrapper: Wrapper,
+      });
+
+      // ensure that initial effects are done
+      await waitFor(() => {
+        expect(result.current.status).toBe(ContractDownloadStatus.READY);
+      });
+
+      expect(mockCheckArchive).toHaveBeenCalledTimes(1);
+      expect(mockGetArchive).not.toHaveBeenCalled();
+      expect(mockCreateArchive).not.toHaveBeenCalled();
+    });
+
+    it("doDownloadArchive should call 'getArchive' if the archive is ready for download", async () => {
+      const contractArchiveId = faker.string.uuid();
+      storeContractArchiveId(contractArchiveId);
+      mockCheckArchive.mockResolvedValue(true);
+
+      const { result } = renderHook(() => useDownloadContractArchive({ organizationId }), {
+        wrapper: Wrapper,
+      });
+
+      // ensure that initial effects are done
+      await waitFor(() => {
+        expect(result.current.status).toBe(ContractDownloadStatus.READY);
+      });
+      expect(mockCheckArchive).toHaveBeenCalledTimes(1);
+
+      act(() => {
+        result.current.downloadContractArchive();
+      });
+
+      await waitFor(() => {
+        expect(result.current.status).toBe(ContractDownloadStatus.IDLE);
+      });
+
+      expect(mockCheckArchive).toHaveBeenCalledTimes(1);
+      // backend is called to download the archive
+      expect(mockGetArchive).toHaveBeenCalledTimes(1);
+
+      // but not to generate the archive
+      expect(mockCreateArchive).not.toHaveBeenCalled();
+    });
+
+    it("doDownloadArchive should call 'createArchive' if no contractArchiveId is stored", async () => {
+      const { result } = renderHook(() => useDownloadContractArchive({ organizationId }), {
+        wrapper: Wrapper,
+      });
+
+      mockCheckArchive.mockResolvedValue(true);
+      mockCreateArchive.mockResolvedValue(faker.string.uuid());
+      act(() => {
+        result.current.downloadContractArchive();
+      });
+
+      await waitFor(() => {
+        expect(result.current.status).toBe(ContractDownloadStatus.IDLE);
+      });
+
+      expect(mockCreateArchive).toHaveBeenCalledTimes(1);
+      expect(mockCheckArchive).toHaveBeenCalledTimes(1);
+      expect(mockGetArchive).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('with contracts available for download and expired contractArchiveId', () => {
+    let contractArchiveId: string;
+    beforeEach(() => {
+      organizationId = faker.string.uuid();
+      mockHasContractToDownload = true;
+
+      const now = Date.now();
+      const unvalidCreationTime =
+        now - CONTRACT_DOWNLOAD_SETTINGS.contractArchiveLocalVaklidityDurationMs * 2;
+
+      jest.useFakeTimers();
+      jest.setSystemTime(new Date(unvalidCreationTime));
+      contractArchiveId = faker.string.uuid();
+      storeContractArchiveId(contractArchiveId);
+      jest.setSystemTime(new Date(now));
+    });
+
+    afterEach(() => {
+      jest.runOnlyPendingTimers();
+      jest.useRealTimers();
+    });
+
+    it('should return READY status when archive exists on the server', async () => {
+      mockCheckArchive.mockResolvedValue(true);
+
+      const { result } = renderHook(() => useDownloadContractArchive({ organizationId }), {
+        wrapper: Wrapper,
+      });
+
+      // ensure that initial effects are done
+      await waitFor(() => {
+        expect(result.current.status).toBe(ContractDownloadStatus.READY);
+      });
+
+      expect(getStoredContractArchiveId()).toBe(contractArchiveId);
+
+      expect(mockCheckArchive).toHaveBeenCalledTimes(1);
+      expect(mockGetArchive).not.toHaveBeenCalled();
+      expect(mockCreateArchive).not.toHaveBeenCalled();
+    });
+
+    it("should return IDLE status and clear stored id when archive doesn't exists on the server", async () => {
+      mockCheckArchive.mockResolvedValue(false);
+
+      const { result } = renderHook(() => useDownloadContractArchive({ organizationId }), {
+        wrapper: Wrapper,
+      });
+
+      // ensure that initial effects are done
+      await waitFor(() => {
+        expect(result.current.status).toBe(ContractDownloadStatus.IDLE);
+      });
+
+      expect(getStoredContractArchiveId()).toBe(null);
+
+      expect(mockCheckArchive).toHaveBeenCalledTimes(1);
+      expect(mockGetArchive).not.toHaveBeenCalled();
+      expect(mockCreateArchive).not.toHaveBeenCalled();
+    });
+  });
+});

package/js/pages/TeacherDashboardContractsLayout/hooks/useDownloadContractArchive/index.tsx

@@ -0,0 +1,153 @@
+import { useEffect, useMemo, useState } from 'react';
+import useContractArchive from 'hooks/useContractArchive';
+import useCheckContractArchiveExists from '../useCheckContractArchiveExists';
+import useHasContractToDownload from '../useHasContractToDownload';
+import {
+  storeContractArchiveId,
+  unstoreContractArchiveId,
+  getStoredContractArchiveId,
+  isStoredContractArchiveIdExpired,
+} from './contractArchiveLocalStorage';
+
+export enum ContractDownloadStatus {
+  INITIALIZING = 'initializing',
+  IDLE = 'idle',
+  PENDING = 'pending',
+  READY = 'ready',
+}
+
+interface UseTeacherContractsBulkDownloadProps {
+  organizationId: string;
+}
+
+const useDownloadContractArchive = ({ organizationId }: UseTeacherContractsBulkDownloadProps) => {
+  // Contract's archive api interface
+  const {
+    methods: { get: getArchive, create: createArchive },
+  } = useContractArchive();
+
+  // Simple hook that verifiy if current user have some fully signed contracts to download.
+  const hasContractToDownload = useHasContractToDownload(organizationId);
+
+  // Component state of the localstorage contract's archive id
+  const [contractArchiveId, setContractArchiveId] = useState<string | null>(
+    getStoredContractArchiveId(),
+  );
+
+  // Hook that handle contract archive existence check and recursive polling of it.
+  const { isPolling, isContractArchiveExists, checkArchiveExists } = useCheckContractArchiveExists({
+    enable: !!hasContractToDownload,
+  });
+
+  // Stored contract's archive id have to be cleanup at some point.
+  // this expired logic is handle by ./contractArchiveLocalStorage and
+  // this isContractArchiveIdExpired track it at a component level.
+  const [isContractArchiveIdExpired, setIsContractArchiveIdExpired] = useState<boolean | null>(
+    null,
+  );
+
+  // This state track if the user have request the download or not.
+  // if he have click the download button, it will be true.
+  // if he just load the page, it will be false.
+  const [isDownloadRequest, setIsDownloadRequest] = useState(false);
+
+  // Here we compute the download status.
+  // It stay as INITIALIZING until all needed data get fetched.
+  // Then it become either:
+  // * READY: the archive is ready to be download from the server
+  // * PENDING: the archive is generating on the server
+  // * IDLE: A fresh new download process
+  const contractDownloadStatus = useMemo(() => {
+    if (
+      [hasContractToDownload, isContractArchiveExists, isContractArchiveIdExpired].includes(null)
+    ) {
+      return ContractDownloadStatus.INITIALIZING;
+    }
+
+    if (hasContractToDownload && contractArchiveId) {
+      if (isContractArchiveExists) {
+        return ContractDownloadStatus.READY;
+      }
+
+      return ContractDownloadStatus.PENDING;
+    }
+
+    return ContractDownloadStatus.IDLE;
+  }, [
+    hasContractToDownload,
+    contractArchiveId,
+    isContractArchiveExists,
+    isContractArchiveIdExpired,
+  ]);
+
+  const clearContractArchive = () => {
+    setIsDownloadRequest(false);
+    setContractArchiveId(null);
+    unstoreContractArchiveId();
+  };
+
+  // Either download the archive
+  // or flag the download as requested and request the archive's creation
+  const downloadContractArchive = async () => {
+    if (isContractArchiveExists && contractArchiveId !== null) {
+      await getArchive(contractArchiveId);
+      clearContractArchive();
+    } else {
+      // When archive is ready and download is requested
+      // a useEffect will trigger the download.
+      setIsDownloadRequest(true);
+      createContractArchive();
+    }
+  };
+
+  // Request the archive's creation if needed
+  // then can start archive's polling (if option.polling === true)
+  const createContractArchive = async () => {
+    let newContractArchiveId;
+    if (contractArchiveId === null) {
+      newContractArchiveId = await createArchive(organizationId);
+      setContractArchiveId(newContractArchiveId);
+      storeContractArchiveId(newContractArchiveId);
+    } else {
+      newContractArchiveId = contractArchiveId;
+    }
+
+    if (!isPolling) {
+      checkArchiveExists(newContractArchiveId, { polling: true });
+    }
+  };
+
+  // Here we check the validity of stored id timestamp
+  // if an id is expired, we'll either:
+  // * when it exists on the server: switch expired state but nothing else
+  // * when didn't exists on the server: switch expired state and clear download data.
+  useEffect(() => {
+    if (isContractArchiveExists === null) {
+      return;
+    }
+
+    if (isStoredContractArchiveIdExpired() && isContractArchiveExists === false) {
+      setIsContractArchiveIdExpired(true);
+      clearContractArchive();
+    } else {
+      setIsContractArchiveIdExpired(false);
+    }
+  }, [contractDownloadStatus, isContractArchiveExists]);
+
+  // When the archive become ready for download
+  // this effect will trigger the download
+  // if it have been previously requested by the user
+  useEffect(() => {
+    if (isDownloadRequest && isContractArchiveExists) {
+      downloadContractArchive();
+    }
+  }, [isDownloadRequest, isContractArchiveExists]);
+
+  return {
+    status: contractDownloadStatus,
+    downloadContractArchive,
+    createContractArchive,
+  };
+};
+
+export default useDownloadContractArchive;