feat: notifiy the editor about subscriptions

Author: chrishelgert

src/__tests__/liveUpdates.spec.ts

@@ -1,14 +1,28 @@
-import { describe, it, vi, expect } from 'vitest';
+import { describe, it, vi, expect, beforeEach, afterEach } from 'vitest';
 
-import { clone } from '../helpers';
+import * as helpers from '../helpers';
 import { LiveUpdates } from '../liveUpdates';
 import assetFromEntryEditor from './fixtures/assetFromEntryEditor.json';
 import landingPageContentType from './fixtures/landingPageContentType.json';
 import nestedCollectionFromPreviewApp from './fixtures/nestedCollectionFromPreviewApp.json';
 import nestedDataFromPreviewApp from './fixtures/nestedDataFromPreviewApp.json';
 import pageInsideCollectionFromEntryEditor from './fixtures/pageInsideCollectionFromEntryEditor.json';
 
+vi.mock('../helpers/debug');
+
 describe('LiveUpdates', () => {
+  const sendMessage = vi.spyOn(helpers, 'sendMessageToEditor');
+
+  beforeEach(() => {
+    sendMessage.mockImplementation(() => {
+      // noop
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
   const contentType = {
     fields: [
       {
@@ -51,6 +65,34 @@ describe('LiveUpdates', () => {
     });
   });
 
+  describe('invalid subscription data', () => {
+    it('should notifiy because sys information is missing', () => {
+      const liveUpdates = new LiveUpdates();
+      const data = { title: 'Data 1', __typename: 'Demo' };
+      const cb = vi.fn();
+
+      liveUpdates.subscribe(data, locale, cb);
+
+      expect(helpers.debug.error).toHaveBeenCalledWith(
+        'Live Updates requires the "sys.id" to be present on the provided data',
+        data
+      );
+    });
+
+    it('should notifiy because we dont know if it is REST or GraphQL', () => {
+      const liveUpdates = new LiveUpdates();
+      const data = { sys: { id: '1' }, title: 'Data 1' };
+      const cb = vi.fn();
+
+      liveUpdates.subscribe(data, locale, cb);
+
+      expect(helpers.debug.error).toHaveBeenCalledWith(
+        'For live updates as a basic requirement the provided data must include the "fields" property for REST or "__typename" for Graphql, otherwise the data will be treated as invalid and live updates will not work.',
+        data
+      );
+    });
+  });
+
   it('no longer receives updates after unsubcribing', () => {
     const liveUpdates = new LiveUpdates();
     const data = { sys: { id: '1' }, title: 'Data 1', __typename: 'Demo' };
@@ -71,7 +113,7 @@ describe('LiveUpdates', () => {
 
   it('ignores invalid messages', () => {
     const liveUpdates = new LiveUpdates();
-    const data = { sys: { id: '1' }, title: 'Data 1' };
+    const data = { sys: { id: '1' }, title: 'Data 1', __typename: 'Demo' };
     const cb = vi.fn();
     liveUpdates.subscribe(data, locale, cb);
 
@@ -97,7 +139,7 @@ describe('LiveUpdates', () => {
     liveUpdates.subscribe(nestedDataFromPreviewApp, locale, cb);
     liveUpdates.receiveMessage({ entity: assetFromEntryEditor });
 
-    const expected = clone(nestedDataFromPreviewApp);
+    const expected = helpers.clone(nestedDataFromPreviewApp);
     expected.featuredImage.title = assetFromEntryEditor.fields.title[locale];
     (expected.featuredImage.description as string | null) =
       assetFromEntryEditor.fields.description[locale];
@@ -114,12 +156,40 @@ describe('LiveUpdates', () => {
       contentType: landingPageContentType,
     });
 
-    const expected = clone(nestedCollectionFromPreviewApp);
+    const expected = helpers.clone(nestedCollectionFromPreviewApp);
     expected.items[0].menuItemsCollection.items[2].featuredPagesCollection.items[1].pageName =
       pageInsideCollectionFromEntryEditor.fields.pageName[locale];
     expected.items[0].menuItemsCollection.items[2].featuredPagesCollection.items[1].slug =
       pageInsideCollectionFromEntryEditor.fields.slug[locale];
 
     expect(cb).toHaveBeenCalledWith(expected);
   });
+
+  describe('sendMessageToEditor', () => {
+    it('sends a message to the editor for a subscription with GQL data', () => {
+      const liveUpdates = new LiveUpdates();
+      const data = { sys: { id: '1' }, title: 'Data 1', __typename: 'Demo' };
+      const cb = vi.fn();
+      liveUpdates.subscribe(data, locale, cb);
+
+      expect(sendMessage).toHaveBeenCalledTimes(1);
+      expect(sendMessage).toHaveBeenCalledWith({
+        action: 'SUBSCRIBED',
+        type: 'GQL',
+      });
+    });
+
+    it('sends a message to the editor for a subscription with REST data', () => {
+      const liveUpdates = new LiveUpdates();
+      const data = { sys: { id: '1' }, fields: { title: 'Data 1' } };
+      const cb = vi.fn();
+      liveUpdates.subscribe(data, locale, cb);
+
+      expect(sendMessage).toHaveBeenCalledTimes(1);
+      expect(sendMessage).toHaveBeenCalledWith({
+        action: 'SUBSCRIBED',
+        type: 'REST',
+      });
+    });
+  });
 });

src/liveUpdates.ts

@@ -1,7 +1,7 @@
 import type { AssetProps, EntryProps } from 'contentful-management';
 
 import * as gql from './graphql';
-import { clone, generateUID, StorageMap } from './helpers';
+import { clone, generateUID, sendMessageToEditor, StorageMap, debug } from './helpers';
 import * as rest from './rest';
 import {
   Argument,
@@ -210,16 +210,66 @@ export class LiveUpdates {
     }
   }
 
+  /**
+   * **Basic** validating of the subscribed data
+   * Is it GraphQL or REST and does it contain the sys information
+   * TODO: add more accurate checks
+   */
+  private validateDataFromPreview(data: Argument) {
+    const dataAsString = JSON.stringify(data);
+
+    const isGQL = dataAsString.includes('__typename');
+    const isREST = dataAsString.includes('fields":{');
+    const hasSys = dataAsString.includes('sys":{');
+
+    let isValid = true;
+
+    if (!hasSys) {
+      isValid = false;
+      debug.error('Live Updates requires the "sys.id" to be present on the provided data', data);
+    }
+
+    if (!isGQL && !isREST) {
+      isValid = false;
+      debug.error(
+        'For live updates as a basic requirement the provided data must include the "fields" property for REST or "__typename" for Graphql, otherwise the data will be treated as invalid and live updates will not work.',
+        data
+      );
+    }
+
+    return {
+      isGQL,
+      isREST,
+      hasSys,
+      isValid,
+    };
+  }
+
   /**
    * Subscribe to data changes from the Editor, returns a function to unsubscribe
    * Will be called once initially for the restored data
    */
   public subscribe(data: Argument, locale: string, cb: SubscribeCallback): VoidFunction {
+    const { isGQL, isValid } = this.validateDataFromPreview(data);
+
+    if (!isValid) {
+      return () => {
+        /* noop */
+      };
+    }
+
     const id = generateUID();
     this.subscriptions.set(id, { data, locale, cb });
     // TODO: https://contentful.atlassian.net/browse/TOL-1080
     // this.restore(data, cb);
 
+    // Tell the editor that there is a subscription
+    // It's possible that the `type` is not 100% accurate as we don't know how it will be merged in the future.
+    sendMessageToEditor({
+      action: 'SUBSCRIBED',
+      type: isGQL ? 'GQL' : 'REST',
+    });
+
     return () => {
       this.subscriptions.delete(id);
     };

src/types.ts

@@ -66,11 +66,17 @@ type UrlChangedMessage = {
   action: 'URL_CHANGED';
 };
 
+type SubscribedMessage = {
+  action: 'SUBSCRIBED';
+  type: 'GQL' | 'REST';
+};
+
 export type EditorMessage =
   | IframeConnectedMessage
   | TaggedFieldClickMessage
   | UnknownEntityMessage
-  | UrlChangedMessage;
+  | UrlChangedMessage
+  | SubscribedMessage;
 
 export type MessageFromSDK = EditorMessage & {
   from: 'live-preview';