Add AnnotationActivityService

Add new service to notify ancestor frame on annotation activity, if
so configured.

src/sidebar/index.js

@@ -113,6 +113,7 @@ import { ServiceContext } from './service-context';
 
 // Services.
 import { AnnotationsService } from './services/annotations';
+import { AnnotationActivityService } from './services/annotation-activity';
 import { APIService } from './services/api';
 import { APIRoutesService } from './services/api-routes';
 import { AuthService } from './services/auth';
@@ -150,6 +151,7 @@ function startApp(settings, appEl) {
   // Register services.
   container
     .register('annotationsService', AnnotationsService)
+    .register('annotationActivity', AnnotationActivityService)
     .register('api', APIService)
     .register('apiRoutes', APIRoutesService)
     .register('auth', AuthService)

src/sidebar/services/annotation-activity.js

+import * as postMessageJsonRpc from '../util/postmessage-json-rpc';
+
+/**
+ * @typedef {import('../../types/api').Annotation} Annotation
+ * @typedef {import('../../types/config').SidebarSettings} SidebarSettings
+ * @typedef {import('../../types/config').AnnotationEventType} AnnotationEventType
+ */
+
+/**
+ * Send messages to configured ancestor frame on annotation activity
+ */
+// @inject
+export class AnnotationActivityService {
+  /**
+   * @param {SidebarSettings} settings
+   */
+  constructor(settings) {
+    this._rpc = settings.rpc;
+    this._reportConfig = settings.reportActivity;
+  }
+
+  /**
+   * @param {AnnotationEventType} eventType
+   * @param {Annotation} annotation
+   */
+  reportActivity(eventType, annotation) {
+    if (!this._rpc || !this._reportConfig) {
+      return;
+    }
+
+    // Determine the appropriate ISO-8601 timestamp for this "activity"
+    let activityDate;
+    switch (eventType) {
+      case 'create':
+        activityDate = new Date(annotation.created).toISOString();
+        break;
+      case 'update':
+        activityDate = new Date(annotation.updated).toISOString();
+        break;
+      default:
+        activityDate = new Date().toISOString();
+    }
+
+    const data = {
+      date: activityDate,
+      annotation: {
+        id: annotation.id,
+      },
+    };
+
+    if (this._reportConfig.events.includes(eventType)) {
+      postMessageJsonRpc.call(
+        this._rpc.targetFrame,
+        this._rpc.origin,
+        this._reportConfig.method,
+        [eventType, data],
+        3000
+      );
+    }
+  }
+}

src/sidebar/services/annotations.js

@@ -20,9 +20,11 @@ import {
 export class AnnotationsService {
   /**
    * @param {import('./api').APIService} api
+   * @param {import('./annotation-activity').AnnotationActivityService} annotationActivity
    * @param {import('../store').SidebarStore} store
    */
-  constructor(api, store) {
+  constructor(annotationActivity, api, store) {
+    this._activity = annotationActivity;
     this._api = api;
     this._store = store;
   }
@@ -167,6 +169,7 @@ export class AnnotationsService {
    */
   async delete(annotation) {
     await this._api.annotation.delete({ id: annotation.id });
+    this._activity.reportActivity('delete', annotation);
     this._store.removeAnnotations([annotation]);
   }
 
@@ -177,6 +180,7 @@ export class AnnotationsService {
    */
   async flag(annotation) {
     await this._api.annotation.flag({ id: annotation.id });
+    this._activity.reportActivity('flag', annotation);
     this._store.updateFlagStatus(annotation.id, true);
   }
 
@@ -208,22 +212,27 @@ export class AnnotationsService {
    */
   async save(annotation) {
     let saved;
+    /** @type {import('../../types/config').AnnotationEventType} */
+    let eventType;
 
     const annotationWithChanges = this._applyDraftChanges(annotation);
 
     if (!metadata.isSaved(annotation)) {
       saved = this._api.annotation.create({}, annotationWithChanges);
+      eventType = 'create';
     } else {
       saved = this._api.annotation.update(
         { id: annotation.id },
         annotationWithChanges
       );
+      eventType = 'update';
     }
 
     let savedAnnotation;
     this._store.annotationSaveStarted(annotation);
     try {
       savedAnnotation = await saved;
+      this._activity.reportActivity(eventType, savedAnnotation);
     } finally {
       this._store.annotationSaveFinished(annotation);
     }

src/sidebar/services/test/annotation-activity-test.js

+import * as fixtures from '../../test/annotation-fixtures';
+
+import { AnnotationActivityService, $imports } from '../annotation-activity';
+
+describe('AnnotationActivityService', () => {
+  let fakePostMessageJsonRpc;
+
+  let fakeRpcSettings;
+  let fakeReportActivity;
+  let fakeSettings;
+
+  beforeEach(() => {
+    fakePostMessageJsonRpc = {
+      call: sinon.stub(),
+    };
+
+    fakeRpcSettings = {
+      targetFrame: window,
+      origin: 'https://www.example.com',
+    };
+
+    fakeReportActivity = {
+      method: 'remoteMethod',
+      events: ['create', 'update'],
+    };
+
+    fakeSettings = {
+      reportActivity: fakeReportActivity,
+      rpc: fakeRpcSettings,
+    };
+
+    $imports.$mock({
+      '../util/postmessage-json-rpc': fakePostMessageJsonRpc,
+    });
+  });
+
+  afterEach(() => {
+    $imports.$restore();
+  });
+
+  describe('#reportActivity', () => {
+    it('invokes remote activity method if configured for annotation event type', () => {
+      const svc = new AnnotationActivityService(fakeSettings);
+      const annotation = fixtures.defaultAnnotation();
+
+      svc.reportActivity('update', annotation);
+
+      assert.calledOnce(fakePostMessageJsonRpc.call);
+      assert.calledWith(
+        fakePostMessageJsonRpc.call,
+        window,
+        'https://www.example.com',
+        'remoteMethod'
+      );
+    });
+
+    it('invokes remote method with eventType and data arguments', () => {
+      const svc = new AnnotationActivityService(fakeSettings);
+      const annotation = fixtures.defaultAnnotation();
+
+      svc.reportActivity('update', annotation);
+
+      const eventType = fakePostMessageJsonRpc.call.getCall(0).args[3][0];
+      const data = fakePostMessageJsonRpc.call.getCall(0).args[3][1];
+
+      assert.equal(eventType, 'update');
+      assert.deepEqual(data, {
+        // Creating a new Date here is necessary to account for precision differences
+        // betwen server dates (microsecond precision) and JS (millisecond)
+        date: new Date(annotation.updated).toISOString(),
+        annotation: {
+          id: annotation.id,
+        },
+      });
+    });
+
+    it('does not invoke remote activity method if RPC configuration not present', () => {
+      const svc = new AnnotationActivityService({
+        reportActivity: fakeReportActivity,
+      });
+      const annotation = fixtures.defaultAnnotation();
+
+      svc.reportActivity('update', annotation);
+
+      assert.notCalled(fakePostMessageJsonRpc.call);
+    });
+
+    it('does not invoke remote activity method if reportActivity not configured', () => {
+      const svc = new AnnotationActivityService({ rpc: fakeRpcSettings });
+      const annotation = fixtures.defaultAnnotation();
+
+      svc.reportActivity('update', annotation);
+
+      assert.notCalled(fakePostMessageJsonRpc.call);
+    });
+
+    it('does not invoke remote activity method if annotation event type is not one of configured events', () => {
+      const svc = new AnnotationActivityService(fakeSettings);
+      const annotation = fixtures.defaultAnnotation();
+
+      svc.reportActivity('delete', annotation);
+
+      assert.notCalled(fakePostMessageJsonRpc.call);
+    });
+
+    it('uses annotation created date as `date` for `create` events', () => {
+      const svc = new AnnotationActivityService(fakeSettings);
+      const annotation = fixtures.defaultAnnotation();
+
+      svc.reportActivity('create', annotation);
+
+      const data = fakePostMessageJsonRpc.call.getCall(0).args[3][1];
+
+      assert.equal(data.date, new Date(annotation.created).toISOString());
+    });
+
+    it('uses annotation updated date as `date` for `update` events', () => {
+      const svc = new AnnotationActivityService(fakeSettings);
+      const annotation = fixtures.defaultAnnotation();
+
+      svc.reportActivity('update', annotation);
+
+      const data = fakePostMessageJsonRpc.call.getCall(0).args[3][1];
+
+      assert.equal(data.date, new Date(annotation.updated).toISOString());
+    });
+
+    describe('using current time for other event type dates', () => {
+      let clock;
+      let now;
+
+      before(() => {
+        now = new Date();
+        clock = sinon.useFakeTimers(now);
+      });
+
+      after(() => {
+        clock.restore();
+      });
+
+      it('uses current date as date for other event types', () => {
+        fakeReportActivity.events = ['delete'];
+        const svc = new AnnotationActivityService(fakeSettings);
+        const annotation = fixtures.defaultAnnotation();
+
+        svc.reportActivity('delete', annotation);
+
+        const data = fakePostMessageJsonRpc.call.getCall(0).args[3][1];
+        assert.equal(data.date, now.toISOString());
+      });
+    });
+  });
+});

src/sidebar/services/test/annotations-test.js

@@ -3,6 +3,7 @@ import * as fixtures from '../../test/annotation-fixtures';
 import { AnnotationsService, $imports } from '../annotations';
 
 describe('AnnotationsService', () => {
+  let fakeAnnotationActivity;
   let fakeApi;
   let fakeMetadata;
   let fakeStore;
@@ -14,6 +15,9 @@ describe('AnnotationsService', () => {
   let svc;
 
   beforeEach(() => {
+    fakeAnnotationActivity = {
+      reportActivity: sinon.stub(),
+    };
     fakeApi = {
       annotation: {
         create: sinon.stub().resolves(fixtures.defaultAnnotation()),
@@ -64,7 +68,7 @@ describe('AnnotationsService', () => {
       },
     });
 
-    svc = new AnnotationsService(fakeApi, fakeStore);
+    svc = new AnnotationsService(fakeAnnotationActivity, fakeApi, fakeStore);
   });
 
   afterEach(() => {
@@ -286,6 +290,13 @@ describe('AnnotationsService', () => {
       await assert.rejects(svc.delete(annot), 'Annotation does not exist');
       assert.notCalled(fakeStore.removeAnnotations);
     });
+
+    it('reports delete-annotation activity', async () => {
+      const annot = fixtures.defaultAnnotation();
+      await svc.delete(annot);
+      assert.calledOnce(fakeAnnotationActivity.reportActivity);
+      assert.calledWith(fakeAnnotationActivity.reportActivity, 'delete', annot);
+    });
   });
 
   describe('flag', () => {
@@ -308,6 +319,13 @@ describe('AnnotationsService', () => {
       await assert.rejects(svc.flag(annot), 'Annotation does not exist');
       assert.notCalled(fakeStore.updateFlagStatus);
     });
+
+    it('reports flag-annotation activity', async () => {
+      const annot = fixtures.defaultAnnotation();
+      await svc.flag(annot);
+      assert.calledOnce(fakeAnnotationActivity.reportActivity);
+      assert.calledWith(fakeAnnotationActivity.reportActivity, 'flag', annot);
+    });
   });
 
   describe('reply', () => {
@@ -383,6 +401,19 @@ describe('AnnotationsService', () => {
       });
     });
 
+    it('reports create-annotation activity for new annotations', async () => {
+      fakeMetadata.isSaved.returns(false);
+      const annotation = fixtures.newAnnotation();
+
+      const savedAnnotation = await svc.save(annotation);
+      assert.calledOnce(fakeAnnotationActivity.reportActivity);
+      assert.calledWith(
+        fakeAnnotationActivity.reportActivity,
+        'create',
+        savedAnnotation
+      );
+    });
+
     it('calls the `update` API service for pre-existing annotations', () => {
       fakeMetadata.isSaved.returns(true);
 
@@ -395,6 +426,19 @@ describe('AnnotationsService', () => {
       });
     });
 
+    it('reports update-annotation activity for pre-existing annotations', async () => {
+      fakeMetadata.isSaved.returns(true);
+      const annotation = fixtures.defaultAnnotation();
+
+      const savedAnnotation = await svc.save(annotation);
+      assert.calledOnce(fakeAnnotationActivity.reportActivity);
+      assert.calledWith(
+        fakeAnnotationActivity.reportActivity,
+        'update',
+        savedAnnotation
+      );
+    });
+
     it('calls the relevant API service with an object that has any draft changes integrated', () => {
       fakeMetadata.isSaved.returns(false);
       fakePrivatePermissions.returns({ read: ['foo'] });

src/types/config.js

@@ -68,12 +68,12 @@
  * An "embedder frame" may provide configuration to be notified (via JSON RPC)
  * of qualifying annotation activity from the sidebar frame.
  *
- * @typedef {'create'|'save'|'delete'} AnnotationActivityEvent
+ * @typedef {'create'|'update'|'flag'|'delete'} AnnotationEventType
  *
  * @typedef ReportAnnotationActivityConfig
  *   @prop {string} method - Name of method to call in embedder frame on
  *     qualifying annotation activity
- *   @prop {AnnotationActivityEvent[]} events - Which events to notify about
+ *   @prop {AnnotationEventType[]} events - Which events to notify about
  *
  */