feat(api): Add initial annotations api module and factory (#2089)

* feat(api): Add initial annotations api module and factory

* feat(api): Update file_version type property value

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Author: jstoffan

src/api/APIFactory.js

@@ -23,6 +23,7 @@ import MetadataAPI from './Metadata';
 import FileCollaboratorsAPI from './FileCollaborators';
 import FeedAPI from './Feed';
 import AppIntegrationsAPI from './AppIntegrations';
+import AnnotationsAPI from './Annotations';
 import OpenWithAPI from './OpenWith';
 import MetadataQueryAPI from './MetadataQuery';
 import BoxEditAPI from './box-edit';
@@ -144,6 +145,11 @@ class APIFactory {
      */
     boxEditAPI: BoxEditAPI;
 
+    /**
+     * @property {AnnotationsAPI}
+     */
+    annotationsAPI: AnnotationsAPI;
+
     /**
      * [constructor]
      *
@@ -268,6 +274,11 @@ class APIFactory {
             delete this.openWithAPI;
         }
 
+        if (this.annotationsAPI) {
+            this.annotationsAPI.destroy();
+            delete this.annotationsAPI;
+        }
+
         if (destroyCache) {
             this.options.cache = new Cache();
         }
@@ -592,6 +603,20 @@ class APIFactory {
         this.boxEditAPI = new BoxEditAPI();
         return this.boxEditAPI;
     }
+
+    /**
+     * API for Annotations
+     *
+     * @return {AnnotationsAPI} AnnotationsAPI instance
+     */
+    getAnnotationsAPI(shouldDestroy: boolean): AnnotationsAPI {
+        if (shouldDestroy) {
+            this.destroy();
+        }
+
+        this.annotationsAPI = new AnnotationsAPI(this.options);
+        return this.annotationsAPI;
+    }
 }
 
 export default APIFactory;

src/api/Annotations.js

@@ -0,0 +1,94 @@
+// @flow
+import merge from 'lodash/merge';
+import MarkerBasedApi from './MarkerBasedAPI';
+import type { Annotation, NewAnnotation } from '../common/types/annotations';
+import type { ElementsXhrError } from '../common/types/api';
+
+export default class Annotations extends MarkerBasedApi {
+    getUrl() {
+        return `${this.getBaseApiUrl()}/internal_annotations`;
+    }
+
+    getUrlForId(annotationId: string) {
+        return `${this.getUrl()}/${annotationId}`;
+    }
+
+    createAnnotation(
+        fileId: string,
+        fileVersionId: string,
+        payload: NewAnnotation,
+        successCallback: (annotation: Annotation) => void,
+        errorCallback: (e: ElementsXhrError, code: string) => void,
+    ): Promise<void> {
+        const defaults = {
+            description: {
+                type: 'reply',
+            },
+            file_version: {
+                id: fileVersionId,
+                type: 'file_version',
+            },
+            status: 'open',
+            type: 'annotation',
+        };
+
+        return this.post({
+            id: fileId,
+            data: {
+                data: merge(defaults, payload),
+            },
+            errorCallback,
+            successCallback,
+            url: this.getUrl(),
+        });
+    }
+
+    deleteAnnotation(
+        fileId: string,
+        annotationId: string,
+        successCallback: () => void,
+        errorCallback: (e: ElementsXhrError, code: string) => void,
+    ): Promise<void> {
+        return this.delete({
+            id: fileId,
+            errorCallback,
+            successCallback,
+            url: this.getUrlForId(annotationId),
+        });
+    }
+
+    getAnnotation(
+        fileId: string,
+        annotationId: string,
+        successCallback: (annotation: Annotation) => void,
+        errorCallback: (e: ElementsXhrError, code: string) => void,
+    ): Promise<void> {
+        return this.get({
+            id: fileId,
+            errorCallback,
+            successCallback,
+            url: this.getUrlForId(annotationId),
+        });
+    }
+
+    getAnnotations(
+        fileId: string,
+        fileVersionId?: string,
+        successCallback: (annotations: Annotation[]) => void,
+        errorCallback: (e: ElementsXhrError, code: string) => void,
+        limit?: number,
+        shouldFetchAll?: boolean,
+    ): Promise<void> {
+        return this.markerGet({
+            id: fileId,
+            errorCallback,
+            limit,
+            requestData: {
+                file_id: fileId,
+                file_version_id: fileVersionId,
+            },
+            shouldFetchAll,
+            successCallback,
+        });
+    }
+}

src/api/__tests__/APIFactory.test.js

@@ -1,4 +1,5 @@
 import Cache from '../../utils/Cache';
+import AnnotationsAPI from '../Annotations';
 import APIFactory from '../APIFactory';
 import ChunkedUploadAPI from '../uploads/MultiputUpload';
 import PlainUploadAPI from '../uploads/PlainUpload';
@@ -50,6 +51,7 @@ describe('api/APIFactory', () => {
             factory.taskCollaboratorsAPI = { destroy: jest.fn() };
             factory.boxEditAPI = { destroy: jest.fn() };
             factory.metadataQueryAPI = { destroy: jest.fn() };
+            factory.annotationsAPI = { destroy: jest.fn() };
             factory.destroy();
             expect(factory.fileAPI).toBeUndefined();
             expect(factory.folderAPI).toBeUndefined();
@@ -65,6 +67,7 @@ describe('api/APIFactory', () => {
             expect(factory.tasksNewAPI).toBeUndefined();
             expect(factory.usersAPI).toBeUndefined();
             expect(factory.metadataQueryAPI).toBeUndefined();
+            expect(factory.annotationsAPI).toBeUndefined();
         });
         test('should not destroy cache by default', () => {
             const { cache } = factory.options;
@@ -407,4 +410,26 @@ describe('api/APIFactory', () => {
             expect(metadataQueryAPI.options.uploadHost).toBe(DEFAULT_HOSTNAME_UPLOAD);
         });
     });
+
+    describe('getAnnotationsAPI', () => {
+        test('should call destroy and return annotations API', () => {
+            const spy = jest.spyOn(factory, 'destroy');
+            const annotationsAPI = factory.getAnnotationsAPI(true);
+            expect(spy).toBeCalled();
+            expect(annotationsAPI).toBeInstanceOf(AnnotationsAPI);
+            expect(annotationsAPI.options.cache).toBeInstanceOf(Cache);
+            expect(annotationsAPI.options.apiHost).toBe(DEFAULT_HOSTNAME_API);
+            expect(annotationsAPI.options.uploadHost).toBe(DEFAULT_HOSTNAME_UPLOAD);
+        });
+
+        test('should not call destroy and return annotations API', () => {
+            const spy = jest.spyOn(factory, 'destroy');
+            const annotationsAPI = factory.getAnnotationsAPI();
+            expect(spy).not.toHaveBeenCalled();
+            expect(annotationsAPI).toBeInstanceOf(AnnotationsAPI);
+            expect(annotationsAPI.options.cache).toBeInstanceOf(Cache);
+            expect(annotationsAPI.options.apiHost).toBe(DEFAULT_HOSTNAME_API);
+            expect(annotationsAPI.options.uploadHost).toBe(DEFAULT_HOSTNAME_UPLOAD);
+        });
+    });
 });

src/api/__tests__/Annotations.test.js

@@ -0,0 +1,145 @@
+import Annotations from '../Annotations';
+
+describe('api/Annotations', () => {
+    let annotations;
+
+    beforeEach(() => {
+        annotations = new Annotations({});
+        annotations.delete = jest.fn();
+        annotations.get = jest.fn();
+        annotations.markerGet = jest.fn();
+        annotations.post = jest.fn();
+        annotations.put = jest.fn();
+    });
+
+    afterEach(() => {
+        annotations.destroy();
+        annotations = null;
+    });
+
+    describe('getUrl()', () => {
+        test('should the return correct url for annotations', () => {
+            expect(annotations.getUrl()).toBe('https://api.box.com/2.0/internal_annotations');
+        });
+    });
+
+    describe('getUrlForId()', () => {
+        test('should return the correct url for a given annotation id', () => {
+            expect(annotations.getUrlForId('test')).toBe('https://api.box.com/2.0/internal_annotations/test');
+        });
+    });
+
+    describe('createAnnotation()', () => {
+        test('should format its parameters and call the post method', () => {
+            const payload = {
+                description: {
+                    message: 'This is a test message.',
+                },
+                target: {
+                    location: {
+                        type: 'page',
+                        value: 1,
+                    },
+                    shape: {
+                        height: 50,
+                        type: 'rect',
+                        width: 50,
+                        x: 10,
+                        y: 10,
+                    },
+                    type: 'region',
+                },
+            };
+            const errorCallback = jest.fn();
+            const successCallback = jest.fn();
+
+            annotations.createAnnotation('12345', '67890', payload, successCallback, errorCallback);
+
+            expect(annotations.post).toBeCalledWith({
+                id: '12345',
+                data: {
+                    data: {
+                        description: {
+                            message: 'This is a test message.',
+                            type: 'reply',
+                        },
+                        file_version: {
+                            id: '67890',
+                            type: 'file_version',
+                        },
+                        status: 'open',
+                        target: {
+                            location: {
+                                type: 'page',
+                                value: 1,
+                            },
+                            shape: {
+                                height: 50,
+                                type: 'rect',
+                                width: 50,
+                                x: 10,
+                                y: 10,
+                            },
+                            type: 'region',
+                        },
+                        type: 'annotation',
+                    },
+                },
+                errorCallback,
+                successCallback,
+                url: 'https://api.box.com/2.0/internal_annotations',
+            });
+        });
+    });
+
+    describe('deleteAnnotation()', () => {
+        test('should format its parameters and call the delete method for a given id', () => {
+            const errorCallback = jest.fn();
+            const successCallback = jest.fn();
+
+            annotations.deleteAnnotation('12345', 'abc', successCallback, errorCallback);
+
+            expect(annotations.delete).toBeCalledWith({
+                id: '12345',
+                errorCallback,
+                successCallback,
+                url: 'https://api.box.com/2.0/internal_annotations/abc',
+            });
+        });
+    });
+
+    describe('getAnnotation()', () => {
+        test('should format its parameters and call the get method', () => {
+            const successCallback = jest.fn();
+            const errorCallback = jest.fn();
+
+            annotations.getAnnotation('12345', 'abc', successCallback, errorCallback);
+
+            expect(annotations.get).toBeCalledWith({
+                id: '12345',
+                errorCallback,
+                successCallback,
+                url: 'https://api.box.com/2.0/internal_annotations/abc',
+            });
+        });
+    });
+
+    describe('getAnnotations()', () => {
+        test('should format its parameters and call the underlying markerGet method', () => {
+            const successCallback = jest.fn();
+            const errorCallback = jest.fn();
+
+            annotations.getAnnotations('12345', '67890', successCallback, errorCallback);
+
+            expect(annotations.markerGet).toBeCalledWith({
+                id: '12345',
+                errorCallback,
+                requestData: {
+                    file_id: '12345',
+                    file_version_id: '67890',
+                },
+                successCallback,
+            });
+        });
+    });
+});