[communication-common] Add cloud property and optional full id to identfiers, lowercase kind (Azure#13306)

Author: DominikMe

sdk/communication/communication-common/CHANGELOG.md

@@ -5,9 +5,11 @@
 ### Added
 
 - Added `MicrosoftTeamsUserIdentifier` and `isMicrosoftTeamsUserIdentifier`.
+- Added optional `id` property to communication identifiers.
 
 ### Breaking Changes
 
+- Changed identifier `kind` property to use lowerCamelCase.
 - Renamed `CommunicationUserCredential` to `CommunicationTokenCredential`.
 - Renamed `RefreshOptions` to `CommunicationTokenRefreshOptions`.
 - Renamed `Identifier` to `CommunicationIdentifier`.

sdk/communication/communication-common/review/communication-common.api.md

@@ -19,13 +19,13 @@ export class AzureCommunicationTokenCredential implements CommunicationTokenCred
     }
 
 // @public
-export interface CallingApplicationIdentifier {
+export interface CallingApplicationIdentifier extends WithOptionalFullId {
     callingApplicationId: string;
 }
 
 // @public
 export interface CallingApplicationKind extends CallingApplicationIdentifier {
-    kind: "CallingApplication";
+    kind: "callingApplication";
 }
 
 // @public
@@ -48,13 +48,13 @@ export interface CommunicationTokenRefreshOptions {
 }
 
 // @public
-export interface CommunicationUserIdentifier {
+export interface CommunicationUserIdentifier extends WithOptionalFullId {
     communicationUserId: string;
 }
 
 // @public
 export interface CommunicationUserKind extends CommunicationUserIdentifier {
-    kind: "CommunicationUser";
+    kind: "communicationUser";
 }
 
 // @public
@@ -94,14 +94,15 @@ export const isPhoneNumberIdentifier: (identifier: CommunicationIdentifier) => i
 export const isUnknownIdentifier: (identifier: CommunicationIdentifier) => identifier is UnknownIdentifier;
 
 // @public
-export interface MicrosoftTeamsUserIdentifier {
-    isAnonymous: boolean | undefined;
+export interface MicrosoftTeamsUserIdentifier extends WithOptionalFullId {
+    cloud?: "public" | "dod" | "gcch";
+    isAnonymous?: boolean;
     microsoftTeamsUserId: string;
 }
 
 // @public
 export interface MicrosoftTeamsUserKind extends MicrosoftTeamsUserIdentifier {
-    kind: "MicrosoftTeamsUser";
+    kind: "microsoftTeamsUser";
 }
 
 // @public
@@ -111,20 +112,24 @@ export const parseClientArguments: (connectionStringOrUrl: string, credentialOrO
 export const parseConnectionString: (connectionString: string) => EndpointCredential;
 
 // @public
-export interface PhoneNumberIdentifier {
+export interface PhoneNumberIdentifier extends WithOptionalFullId {
     phoneNumber: string;
 }
 
 // @public
 export interface PhoneNumberKind extends PhoneNumberIdentifier {
-    kind: "PhoneNumber";
+    kind: "phoneNumber";
 }
 
 // @internal
 export const _serializeCommunicationIdentifier: (identifier: CommunicationIdentifier) => _SerializedCommunicationIdentifier;
 
+// @internal
+export type _SerializedCommunicationCloudEnvironment = "public" | "dod" | "gcch";
+
 // @internal
 export interface _SerializedCommunicationIdentifier {
+    cloud?: _SerializedCommunicationCloudEnvironment;
     id?: string;
     isAnonymous?: boolean;
     kind: _SerializedCommunicationIdentifierKind;
@@ -142,7 +147,7 @@ export interface UnknownIdentifier {
 
 // @public
 export interface UnknownIdentifierKind extends UnknownIdentifier {
-    kind: "Unknown";
+    kind: "unknown";
 }
 
 // @public
@@ -151,6 +156,11 @@ export type UrlWithCredential = {
     credential: TokenCredential | KeyCredential;
 };
 
+// @public (undocumented)
+export interface WithOptionalFullId {
+    id?: string;
+}
+
 
 // (No @packageDocumentation comment for this package)
 

sdk/communication/communication-common/src/identifierModelSerializer.ts

@@ -33,6 +33,10 @@ export interface _SerializedCommunicationIdentifier {
    * True if the identifier is anonymous.
    */
   isAnonymous?: boolean;
+  /**
+   * The cloud that the identifier belongs to.
+   */
+  cloud?: _SerializedCommunicationCloudEnvironment;
 }
 
 /**
@@ -47,6 +51,17 @@ export type _SerializedCommunicationIdentifierKind =
   | "callingApplication"
   | "microsoftTeamsUser";
 
+/**
+ * @internal
+ * Defines values for CommunicationCloudEnvironment.
+ * This type is the serialized format of the CommunicationCloudEnvironment used in web requests and responses.
+ */
+export type _SerializedCommunicationCloudEnvironment = "public" | "dod" | "gcch";
+
+const addIdIfExisting = <T>(identifier: T, id: string | undefined): T & { id?: string } => {
+  return id === undefined ? identifier : { ...identifier, id };
+};
+
 /**
  * @internal
  * Translates a CommunicationIdentifier to its serialized format for sending a request.
@@ -57,19 +72,26 @@ export const _serializeCommunicationIdentifier = (
 ): _SerializedCommunicationIdentifier => {
   const identifierKind = getIdentifierKind(identifier);
   switch (identifierKind.kind) {
-    case "CommunicationUser":
+    case "communicationUser":
       return { kind: "communicationUser", id: identifierKind.communicationUserId };
-    case "CallingApplication":
+    case "callingApplication":
       return { kind: "callingApplication", id: identifierKind.callingApplicationId };
-    case "PhoneNumber":
-      return { kind: "phoneNumber", phoneNumber: identifierKind.phoneNumber };
-    case "MicrosoftTeamsUser":
-      return {
-        kind: "microsoftTeamsUser",
-        microsoftTeamsUserId: identifierKind.microsoftTeamsUserId,
-        isAnonymous: identifierKind.isAnonymous
-      };
-    case "Unknown":
+    case "phoneNumber":
+      return addIdIfExisting(
+        { kind: "phoneNumber", phoneNumber: identifierKind.phoneNumber },
+        identifierKind.id
+      );
+    case "microsoftTeamsUser":
+      return addIdIfExisting(
+        {
+          kind: "microsoftTeamsUser",
+          microsoftTeamsUserId: identifierKind.microsoftTeamsUserId,
+          isAnonymous: identifierKind.isAnonymous ?? false,
+          cloud: identifierKind.cloud ?? "public"
+        },
+        identifierKind.id
+      );
+    case "unknown":
       return { kind: "unknown", id: identifierKind.id };
     default:
       throw new Error(`Can't serialize an identifier with kind ${(identifierKind as any).kind}`);
@@ -87,32 +109,37 @@ export const _deserializeCommunicationIdentifier = (
   switch (serializedIdentifier.kind) {
     case "communicationUser":
       return {
-        kind: "CommunicationUser",
-        communicationUserId: assertNotNullOrUndefined(serializedIdentifier, "id")
+        kind: "communicationUser",
+        communicationUserId: assertNotNullOrUndefined(serializedIdentifier, "id"),
+        id: assertNotNullOrUndefined(serializedIdentifier, "id")
       };
     case "callingApplication":
       return {
-        kind: "CallingApplication",
-        callingApplicationId: assertNotNullOrUndefined(serializedIdentifier, "id")
+        kind: "callingApplication",
+        callingApplicationId: assertNotNullOrUndefined(serializedIdentifier, "id"),
+        id: assertNotNullOrUndefined(serializedIdentifier, "id")
       };
     case "phoneNumber":
       return {
-        kind: "PhoneNumber",
-        phoneNumber: assertNotNullOrUndefined(serializedIdentifier, "phoneNumber")
+        kind: "phoneNumber",
+        phoneNumber: assertNotNullOrUndefined(serializedIdentifier, "phoneNumber"),
+        id: assertNotNullOrUndefined(serializedIdentifier, "id")
       };
     case "microsoftTeamsUser":
       return {
-        kind: "MicrosoftTeamsUser",
+        kind: "microsoftTeamsUser",
         microsoftTeamsUserId: assertNotNullOrUndefined(
           serializedIdentifier,
           "microsoftTeamsUserId"
         ),
-        isAnonymous: assertNotNullOrUndefined(serializedIdentifier, "isAnonymous")
+        isAnonymous: assertNotNullOrUndefined(serializedIdentifier, "isAnonymous"),
+        cloud: assertNotNullOrUndefined(serializedIdentifier, "cloud"),
+        id: assertNotNullOrUndefined(serializedIdentifier, "id")
       };
     case "unknown":
-      return { kind: "Unknown", id: assertNotNullOrUndefined(serializedIdentifier, "id") };
+      return { kind: "unknown", id: assertNotNullOrUndefined(serializedIdentifier, "id") };
     default:
-      return { kind: "Unknown", id: assertNotNullOrUndefined(serializedIdentifier, "id") };
+      return { kind: "unknown", id: assertNotNullOrUndefined(serializedIdentifier, "id") };
   }
 };
 

sdk/communication/communication-common/src/identifierModels.ts

@@ -11,10 +11,17 @@ export type CommunicationIdentifier =
   | MicrosoftTeamsUserIdentifier
   | UnknownIdentifier;
 
+export interface WithOptionalFullId {
+  /**
+   * Optional full id of the identifier.
+   */
+  id?: string;
+}
+
 /**
  * An Azure Communication user.
  */
-export interface CommunicationUserIdentifier {
+export interface CommunicationUserIdentifier extends WithOptionalFullId {
   /**
    * Id of the CommunicationUser as returned from the Communication Service.
    */
@@ -24,7 +31,7 @@ export interface CommunicationUserIdentifier {
 /**
  * A phone number.
  */
-export interface PhoneNumberIdentifier {
+export interface PhoneNumberIdentifier extends WithOptionalFullId {
   /**
    * The phone number in E.164 format.
    */
@@ -34,7 +41,7 @@ export interface PhoneNumberIdentifier {
 /**
  * A calling application, i.e. a non-human participant in communication.
  */
-export interface CallingApplicationIdentifier {
+export interface CallingApplicationIdentifier extends WithOptionalFullId {
   /**
    * Id of the CallingApplication.
    */
@@ -44,16 +51,21 @@ export interface CallingApplicationIdentifier {
 /**
  * A Microsoft Teams user.
  */
-export interface MicrosoftTeamsUserIdentifier {
+export interface MicrosoftTeamsUserIdentifier extends WithOptionalFullId {
   /**
    * Id of the Microsoft Teams user. If the user isn't anonymous, the id is the AAD object id of the user.
    */
   microsoftTeamsUserId: string;
 
   /**
-   * True if the user is anonymous, for example when joining a meeting with a share link.
+   * True if the user is anonymous, for example when joining a meeting with a share link. If missing, the user is not anonymous.
+   */
+  isAnonymous?: boolean;
+
+  /**
+   * The cloud that the Microsoft Teams user belongs to. If missing, the cloud is "public".
    */
-  isAnonymous: boolean | undefined;
+  cloud?: "public" | "dod" | "gcch";
 }
 
 /**
@@ -138,7 +150,7 @@ export interface CommunicationUserKind extends CommunicationUserIdentifier {
   /**
    * The identifier kind.
    */
-  kind: "CommunicationUser";
+  kind: "communicationUser";
 }
 
 /**
@@ -148,7 +160,7 @@ export interface PhoneNumberKind extends PhoneNumberIdentifier {
   /**
    * The identifier kind.
    */
-  kind: "PhoneNumber";
+  kind: "phoneNumber";
 }
 
 /**
@@ -158,7 +170,7 @@ export interface CallingApplicationKind extends CallingApplicationIdentifier {
   /**
    * The identifier kind.
    */
-  kind: "CallingApplication";
+  kind: "callingApplication";
 }
 
 /**
@@ -168,7 +180,7 @@ export interface MicrosoftTeamsUserKind extends MicrosoftTeamsUserIdentifier {
   /**
    * The identifier kind.
    */
-  kind: "MicrosoftTeamsUser";
+  kind: "microsoftTeamsUser";
 }
 
 /**
@@ -178,7 +190,7 @@ export interface UnknownIdentifierKind extends UnknownIdentifier {
   /**
    * The identifier kind.
    */
-  kind: "Unknown";
+  kind: "unknown";
 }
 
 /**
@@ -190,16 +202,16 @@ export const getIdentifierKind = (
   identifier: CommunicationIdentifier
 ): CommunicationIdentifierKind => {
   if (isCommunicationUserIdentifier(identifier)) {
-    return { ...identifier, kind: "CommunicationUser" };
+    return { ...identifier, kind: "communicationUser" };
   }
   if (isPhoneNumberIdentifier(identifier)) {
-    return { ...identifier, kind: "PhoneNumber" };
+    return { ...identifier, kind: "phoneNumber" };
   }
   if (isCallingApplicationIdentifier(identifier)) {
-    return { ...identifier, kind: "CallingApplication" };
+    return { ...identifier, kind: "callingApplication" };
   }
   if (isMicrosoftTeamsUserIdentifier(identifier)) {
-    return { ...identifier, kind: "MicrosoftTeamsUser" };
+    return { ...identifier, kind: "microsoftTeamsUser" };
   }
-  return { ...identifier, kind: "Unknown" };
+  return { ...identifier, kind: "unknown" };
 };