fix: improve error messaging (#893)

* feat: improve error messaging

* chore: cleanup

* refactor: improve messaging

packages/live-preview-sdk/src/__tests__/init.spec.ts

@@ -69,7 +69,7 @@ describe('init', () => {
 
   it('warns about invalid init call (missing locale)', () => {
     expect(ContentfulLivePreview.init).toThrow(
-      "Init function have to be called with a locale configuration (for example: `ContentfulLivePreview.init({ locale: 'en-US'})`)",
+      "Init function has to be called with a locale configuration (for example: `ContentfulLivePreview.init({ locale: 'en-US'})`)",
     );
   });
 

packages/live-preview-sdk/src/__tests__/react.spec.tsx

@@ -24,7 +24,7 @@ describe('ContentfulLivePreviewProvider', () => {
       // @ts-expect-error -- case locale not provided (e.g. JavaScript usage)
       () => render(<ContentfulLivePreviewProvider>Hello World</ContentfulLivePreviewProvider>),
     ).toThrowError(
-      'ContentfulLivePreviewProvider have to be called with a locale property (for example: `<ContentfulLivePreviewProvider locale="en-US">{children}</ContentfulLivePreviewProvider>`',
+      'ContentfulLivePreviewProvider has to be called with a locale property (for example: `<ContentfulLivePreviewProvider locale="en-US">{children}</ContentfulLivePreviewProvider>`',
     );
 
     spy.mockRestore();

packages/live-preview-sdk/src/index.ts

@@ -92,7 +92,7 @@ export class ContentfulLivePreview {
   static init(config: ContentfulLivePreviewInitConfig): Promise<InspectorMode | null> | undefined {
     if (typeof config !== 'object' || !config?.locale) {
       throw new Error(
-        "Init function have to be called with a locale configuration (for example: `ContentfulLivePreview.init({ locale: 'en-US'})`)",
+        "Init function has to be called with a locale configuration (for example: `ContentfulLivePreview.init({ locale: 'en-US'})`)",
       );
     }
 
@@ -345,6 +345,7 @@ export class ContentfulLivePreview {
     return this.liveUpdatesEnabled;
   }
 
+  //TODO: Rename to openEntityInEditor, as assets can also be opened. Would be breaking change
   static openEntryInEditor(props: LivePreviewProps): void {
     const defaultProps = {
       locale: this.locale,
@@ -374,7 +375,7 @@ export class ContentfulLivePreview {
       return;
     }
 
-    debug.error('Please provide field id and entry id to openEntryInEditor.');
+    debug.error('Please provide field id and entry/asset id to openEntryInEditor.', { ...props });
   }
 
   /**

packages/live-preview-sdk/src/inspectorMode/__tests__/getAllTaggedElements.bench.ts

@@ -91,8 +91,7 @@ describe('getAllTaggedElements', () => {
 
     const elements = getAllTaggedElements({
       root: dom,
-      ignoreManual: true,
-      options: { locale: 'en-US' },
+      options: { locale: 'en-US', ignoreManuallyTaggedElements: true },
     });
 
     expect(elements).toHaveLength(1 + 10 + 30 + 3);

packages/live-preview-sdk/src/inspectorMode/__tests__/getAllTaggedElements.test.ts

@@ -1,6 +1,7 @@
 import { combine } from '@contentful/content-source-maps';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 
+import { setDebugMode } from '../../helpers/debug.js';
 import { InspectorModeDataAttributes, InspectorModeEntryAttributes } from '../types.js';
 import { getAllTaggedElements } from '../utils.js';
 import { createSourceMapFixture } from './fixtures/contentSourceMap.js';
@@ -174,11 +175,15 @@ describe('getAllTaggedElements', () => {
         `<span>${combine('Test', createSourceMapFixture('ignore_origin', { origin: 'example.com' }))}</span>`,
       );
 
+      setDebugMode(true);
+      vi.spyOn(console, 'warn');
+
       const { taggedElements: elements } = getAllTaggedElements({
         root: dom,
         options: { locale: 'en-US' },
       });
       expect(elements).toEqual([]);
+      expect(console.warn).toHaveBeenCalled();
     });
 
     it('should recognize auto-tagged elements', () => {
@@ -392,8 +397,7 @@ describe('getAllTaggedElements', () => {
         manuallyTaggedCount,
       } = getAllTaggedElements({
         root: dom,
-        ignoreManual: true,
-        options: { locale: 'en-US' },
+        options: { locale: 'en-US', ignoreManuallyTaggedElements: true },
       });
 
       expect(elements.length).toEqual(1);

packages/live-preview-sdk/src/inspectorMode/utils.ts

@@ -74,6 +74,16 @@ export function getManualInspectorModeAttributes(
     manuallyTagged: true,
   };
 
+  if (!sharedProps.fieldId) {
+    debug.warn('Element is missing field ID attribute and cannot be tagged', {
+      id:
+        element.getAttribute(InspectorModeDataAttributes.ENTRY_ID) ??
+        element.getAttribute(InspectorModeDataAttributes.ASSET_ID),
+      sharedProps,
+    });
+    return null;
+  }
+
   const entryId = element.getAttribute(InspectorModeDataAttributes.ENTRY_ID);
   if (entryId) {
     return { ...sharedProps, entryId };
@@ -158,18 +168,16 @@ function hasTaggedParent(
 export function getAllTaggedElements({
   root = window.document,
   options,
-  ignoreManual,
 }: {
   root?: any;
   options: Omit<InspectorModeOptions, 'targetOrigin'>;
-  ignoreManual?: boolean;
 }): {
   taggedElements: PrecaulculatedTaggedElement[];
   manuallyTaggedCount: number;
   automaticallyTaggedCount: number;
   autoTaggedElements: AutoTaggedElement<Element>[];
 } {
-  const alreadyTagged = ignoreManual
+  const alreadyTagged = options.ignoreManuallyTaggedElements
     ? []
     : root.querySelectorAll(
         `[${InspectorModeDataAttributes.ASSET_ID}][${InspectorModeDataAttributes.FIELD_ID}], [${InspectorModeDataAttributes.ENTRY_ID}][${InspectorModeDataAttributes.FIELD_ID}]`,
@@ -190,7 +198,13 @@ export function getAllTaggedElements({
   for (const { node, text } of stegaNodes) {
     const sourceMap = decode(text);
     if (!sourceMap || !sourceMap.origin.includes('contentful.com')) {
-      debug.warn;
+      debug.warn(
+        "Element has missing or invalid ContentSourceMap, please check if you have correctly enabled ContentSourceMaps and that the element's data originates from Contentful",
+        {
+          node,
+          sourceMap,
+        },
+      );
       continue;
     }
 

packages/live-preview-sdk/src/liveUpdates.ts

@@ -34,6 +34,17 @@ export class LiveUpdates {
 
       const subscription = this.subscriptions.get(subscriptionId);
 
+      if (!data.sys || !data.sys.id) {
+        debug.error(
+          'Received an update with missing `sys.id`, please provide `sys.id` in order to enable live updates',
+          {
+            data,
+            subscriptionId,
+          },
+        );
+        return;
+      }
+
       if (subscription) {
         subscription.callback(data);
         subscription.data = data;

packages/live-preview-sdk/src/react.tsx

@@ -62,7 +62,7 @@ export function ContentfulLivePreviewProvider({
 }: PropsWithChildren<ContentfulLivePreviewInitConfig>): ReactElement {
   if (!locale) {
     throw new Error(
-      'ContentfulLivePreviewProvider have to be called with a locale property (for example: `<ContentfulLivePreviewProvider locale="en-US">{children}</ContentfulLivePreviewProvider>`',
+      'ContentfulLivePreviewProvider has to be called with a locale property (for example: `<ContentfulLivePreviewProvider locale="en-US">{children}</ContentfulLivePreviewProvider>`',
     );
   }