feat: add type definition to signal recipients

follows more the notifications way of setting recipients and is more
future proof

Signed-off-by: Heikki Hellgren <heikki.hellgren@op.fi>

plugins/signals-node/README.md

@@ -91,13 +91,13 @@ To allow connections from the frontend, you should also install the `@backstage/
 
 Once you have both of the backend plugins installed, you can utilize the signal service by calling the
 `publish` method. This will publish the message to all subscribers in the frontend. To send message to
-all subscribers, you can use `null` as `recipients` parameter.
+all subscribers, you can use `broadcast` type:
 
 ```ts
 // Periodic sending example
 setInterval(async () => {
   await signals.publish({
-    recipients: null,
+    recipients: { type: 'broadcast' },
     channel: 'my_plugin',
     message: {
       message: 'hello world',
@@ -118,7 +118,7 @@ to work:
 eventBroker.publish({
   topic: 'signals',
   eventPayload: {
-    recipients: ['user:default/user1'],
+    recipients: { type: 'user', entityRefs: ['user:default/user1'] },
     message: {
       message: 'hello world',
     },

plugins/signals-node/api-report.md

@@ -21,7 +21,14 @@ export class DefaultSignalsService implements SignalsService {
 
 // @public (undocumented)
 export type SignalPayload<TMessage extends JsonObject = JsonObject> = {
-  recipients: string[] | string | null;
+  recipients:
+    | {
+        type: 'user';
+        entityRefs: string | string[];
+      }
+    | {
+        type: 'broadcast';
+      };
   channel: string;
   message: TMessage;
 };

plugins/signals-node/src/DefaultSignalsService.test.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 import { DefaultSignalsService } from './DefaultSignalsService';
+import { SignalPayload } from './types';
 
 describe('DefaultSignalsService', () => {
   const mockEvents = {
@@ -24,9 +25,9 @@ describe('DefaultSignalsService', () => {
   const service = DefaultSignalsService.create({ events: mockEvents });
 
   it('should publish signal', () => {
-    const signal = {
+    const signal: SignalPayload = {
       channel: 'test-channel',
-      recipients: null,
+      recipients: { type: 'broadcast' },
       message: { msg: 'hello world' },
     };
     service.publish(signal);

plugins/signals-node/src/types.ts

@@ -25,7 +25,9 @@ export type SignalsServiceOptions = {
 
 /** @public */
 export type SignalPayload<TMessage extends JsonObject = JsonObject> = {
-  recipients: string[] | string | null;
+  recipients:
+    | { type: 'user'; entityRefs: string | string[] }
+    | { type: 'broadcast' };
   channel: string;
   message: TMessage;
 };