feat: timer preview

apps/server/src/api-integration/__tests__/integration.legacy.test.ts

@@ -0,0 +1,36 @@
+import { handleLegacyMessageConversion } from '../integration.legacy.js';
+
+describe('handleLegacyConversion', () => {
+  it('should return the payload as is if it is not a legacy message', () => {
+    expect(handleLegacyMessageConversion({})).toEqual({});
+    const newPayload = {
+      timer: {
+        text: 'text',
+        visible: true,
+        blink: true,
+        blackout: true,
+      },
+      external: 'text',
+    };
+    expect(handleLegacyMessageConversion(newPayload)).toEqual(newPayload);
+  });
+
+  it('should convert a legacy payload with external message', () => {
+    expect(handleLegacyMessageConversion({ external: { text: 'text', visible: true } })).toEqual({
+      external: 'text',
+      timer: {
+        secondarySource: 'external',
+      },
+    });
+
+    expect(handleLegacyMessageConversion({ external: { visible: true } })).toEqual({
+      timer: {
+        secondarySource: 'external',
+      },
+    });
+
+    expect(handleLegacyMessageConversion({ external: { text: 'text' } })).toEqual({
+      external: 'text',
+    });
+  });
+});

apps/server/src/api-integration/integration.controller.ts

@@ -1,9 +1,11 @@
-import { DeepPartial, MessageState, OntimeEvent, SimpleDirection, SimplePlayback } from 'ontime-types';
+import { MessageState, OntimeEvent, SimpleDirection, SimplePlayback } from 'ontime-types';
 import { MILLIS_PER_HOUR, MILLIS_PER_SECOND } from 'ontime-utils';
 
+import { DeepPartial } from 'ts-essentials';
+
 import { ONTIME_VERSION } from '../ONTIME_VERSION.js';
 import { auxTimerService } from '../services/aux-timer-service/AuxTimerService.js';
-import { messageService } from '../services/message-service/MessageService.js';
+import * as messageService from '../services/message-service/MessageService.js';
 import { validateMessage, validateTimerMessage } from '../services/message-service/messageUtils.js';
 import { runtimeService } from '../services/runtime-service/RuntimeService.js';
 import { eventStore } from '../stores/EventStore.js';
@@ -14,6 +16,8 @@ import { socket } from '../adapters/WebsocketAdapter.js';
 import { throttle } from '../utils/throttle.js';
 import { willCauseRegeneration } from '../services/rundown-service/rundownCacheUtils.js';
 
+import { handleLegacyMessageConversion } from './integration.legacy.js';
+
 const throttledUpdateEvent = throttle(updateEvent, 20);
 
 export function dispatchFromAdapter(type: string, payload: unknown, _source?: 'osc' | 'ws' | 'http') {
@@ -78,9 +82,12 @@ const actionHandlers: Record<string, ActionHandler> = {
   message: (payload) => {
     assert.isObject(payload);
 
+    // TODO: remove this once we feel its been enough time, ontime 3.6.0, 20/09/2024
+    const migratedPayload = handleLegacyMessageConversion(payload);
+
     const patch: DeepPartial<MessageState> = {
-      timer: 'timer' in payload ? validateTimerMessage(payload.timer) : undefined,
-      external: 'external' in payload ? validateMessage(payload.external) : undefined,
+      timer: 'timer' in migratedPayload ? validateTimerMessage(migratedPayload.timer) : undefined,
+      external: 'external' in migratedPayload ? validateMessage(migratedPayload.external) : undefined,
     };
 
     const newMessage = messageService.patch(patch);

apps/server/src/api-integration/integration.legacy.ts

@@ -0,0 +1,67 @@
+import { MessageState } from 'ontime-types';
+import { DeepPartial } from 'ts-essentials';
+
+export type LegacyMessageState = DeepPartial<{
+  timer: {
+    text: string;
+    visible: boolean;
+    blink: boolean;
+    blackout: boolean;
+  };
+  external: {
+    text: string;
+    visible: boolean;
+  };
+}>;
+
+function isLegacyMessageState(value: object): value is LegacyMessageState {
+  // @ts-expect-error -- good enough here
+  return value?.external?.text !== undefined || value?.external?.visible !== undefined;
+}
+
+/**
+ * This function is used to maintain support for legacy data in the /message endpoint
+ * The previous message endpoint expected a patch of the message state
+ * @example {
+ *  timer: { blink: boolean, blackout: boolean, text: string, visible: boolean },
+ *  external: { visible: boolean, text: string }
+ * }
+ *
+ * This change is introduced in version 3.6.0
+ */
+export function handleLegacyMessageConversion(payload: object): object | Partial<MessageState> {
+  // if it is not a legacy message, we pass it as is
+  if (!isLegacyMessageState(payload)) {
+    return payload;
+  }
+
+  /**
+   * The current migration only needs to handle the cases
+   * for the deprecated external message controls
+   */
+
+  // Migrate external message
+  // 2.1 the user gives us the text and a visible flag
+  if (payload?.external?.text !== undefined && payload.external.visible !== undefined) {
+    return {
+      timer: { secondarySource: payload.external.visible ? 'external' : null },
+      external: payload.external.text,
+    } as Partial<MessageState>;
+  }
+  // 2.2 the user gives us the text
+  else if (payload?.external?.text !== undefined) {
+    return {
+      external: payload.external.text,
+    } as Partial<MessageState>;
+  }
+  // 2.3 the user gives us the visible flag
+  else if (payload?.external?.visible !== undefined) {
+    return {
+      timer: { secondarySource: payload.external.visible ? 'external' : null },
+    } as Partial<MessageState>;
+  }
+
+  // there should be no case for us to reach this since
+  // the type guard would have ensured one of the above states
+  return payload;
+}