Introduce intent URL param and make it change the default lobby behaviour (#2828)

* Introduce `intent` URL param and make it change the default lobby behaviour

* Mark skipLobby as deprecated

* Add support for unknown intent which is default for when not specified

src/UrlParams.test.ts

@@ -7,7 +7,11 @@ Please see LICENSE in the repository root for full details.
 
 import { describe, expect, it } from "vitest";
 
-import { getRoomIdentifierFromUrl, getUrlParams } from "../src/UrlParams";
+import {
+  getRoomIdentifierFromUrl,
+  getUrlParams,
+  UserIntent,
+} from "../src/UrlParams";
 
 const ROOM_NAME = "roomNameHere";
 const ROOM_ID = "!d45f138fsd";
@@ -195,4 +199,48 @@ describe("UrlParams", () => {
       expect(getUrlParams("?homeserver=asd").homeserver).toBe("asd");
     });
   });
+
+  describe("intent", () => {
+    it("defaults to unknown", () => {
+      expect(getUrlParams().intent).toBe(UserIntent.Unknown);
+    });
+
+    it("ignores intent if it is not a valid value", () => {
+      expect(getUrlParams("?intent=foo").intent).toBe(UserIntent.Unknown);
+    });
+
+    it("accepts start_call", () => {
+      expect(getUrlParams("?intent=start_call").intent).toBe(
+        UserIntent.StartNewCall,
+      );
+    });
+
+    it("accepts join_existing", () => {
+      expect(getUrlParams("?intent=join_existing").intent).toBe(
+        UserIntent.JoinExistingCall,
+      );
+    });
+  });
+
+  describe("skipLobby", () => {
+    it("defaults to false", () => {
+      expect(getUrlParams().skipLobby).toBe(false);
+    });
+
+    it("defaults to false if intent is start_call in SPA mode", () => {
+      expect(getUrlParams("?intent=start_call").skipLobby).toBe(false);
+    });
+
+    it("defaults to true if intent is start_call in widget mode", () => {
+      expect(
+        getUrlParams(
+          "?intent=start_call&widgetId=12345&parentUrl=https%3A%2F%2Flocalhost%2Ffoo",
+        ).skipLobby,
+      ).toBe(true);
+    });
+
+    it("default to false if intent is join_existing", () => {
+      expect(getUrlParams("?intent=join_existing").skipLobby).toBe(false);
+    });
+  });
 });

src/UrlParams.ts

@@ -19,6 +19,12 @@ interface RoomIdentifier {
   viaServers: string[];
 }
 
+export enum UserIntent {
+  StartNewCall = "start_call",
+  JoinExistingCall = "join_existing",
+  Unknown = "unknown",
+}
+
 // If you need to add a new flag to this interface, prefer a name that describes
 // a specific behavior (such as 'confineToRoom'), rather than one that describes
 // the situations that call for this behavior ('isEmbedded'). This makes it
@@ -142,6 +148,13 @@ export interface UrlParams {
    * creating a spa link.
    */
   homeserver: string | null;
+
+  /**
+   * The user's intent with respect to the call.
+   * e.g. if they clicked a Start Call button, this would be `start_call`.
+   * If it was a Join Call button, it would be `join_existing`.
+   */
+  intent: string | null;
 }
 
 // This is here as a stopgap, but what would be far nicer is a function that
@@ -211,6 +224,10 @@ export const getUrlParams = (
 
   const fontScale = parseFloat(parser.getParam("fontScale") ?? "");
 
+  let intent = parser.getParam("intent");
+  if (!intent || !Object.values(UserIntent).includes(intent as UserIntent)) {
+    intent = UserIntent.Unknown;
+  }
   const widgetId = parser.getParam("widgetId");
   const parentUrl = parser.getParam("parentUrl");
   const isWidget = !!widgetId && !!parentUrl;
@@ -243,11 +260,15 @@ export const getUrlParams = (
     analyticsID: parser.getParam("analyticsID"),
     allowIceFallback: parser.getFlagParam("allowIceFallback"),
     perParticipantE2EE: parser.getFlagParam("perParticipantE2EE"),
-    skipLobby: parser.getFlagParam("skipLobby"),
+    skipLobby: parser.getFlagParam(
+      "skipLobby",
+      isWidget && intent === UserIntent.StartNewCall,
+    ),
     returnToLobby: isWidget ? parser.getFlagParam("returnToLobby") : true,
     theme: parser.getParam("theme"),
     viaServers: !isWidget ? parser.getParam("viaServers") : null,
     homeserver: !isWidget ? parser.getParam("homeserver") : null,
+    intent,
   };
 };