CallInvite has CustomContext class (#26624)

### Packages impacted by this PR
azure/communication-call-automation

### Issues associated with this PR
#customers' feedback:

SIP UUI format: The format used by ACS (userToUser) is not aligned to
RFC format. Developers being more familiar with the latter, I recommend
we align to RFC format (User-to-User) in SDK as well as EG payload, just
we like we do for custom headers.

In line with No.1, it might be a better experience to manage the strict
header key format at SDK layer, so that every developer doesnt have to
remember to set the correct format in the request.
eg. Instead of callInvite.SipHeaders.Add("userToUser",
"616d617a6f6e5f6368696;encoding=hex");
we do
callInvite.SipHeaders.AddUserToUser("616d617a6f6e5f6368696;encoding=hex");

eg. Instead of callInvite.SipHeaders.Add("X-MS-Custom-",
"434erdr454tf"),
we do callInvite.SipHeaders.AddCustomHeader("", "434erdr454tf");

#Design:
1.1.1 PSTN target
```
CallInvite callInvite = new CallInvite(new PhoneNumberIdentifier(targetParticipant), callerIdNumber);
callInvite.CustomContext.Add(new SIPUUIHeader(“jason”));
callInvite.CustomContext.Add(new SIPCustomHeader("Frank", "Rizzo")); // SDK will add prefix "X-MS-Custom-"
```

Then SDK will send this payload to PMA:
```
customContext: {        
        "sipHeaders":
        {
                "User-to-User": "jason",
                "X-MS-Custom-Frank": "Rizzo"
        }
}
```
1.1.2 VoiP Target
```
CallInvite callInvite = new CallInvite(new CommunicationUserIdentifier(targetParticipant))
callInvite.CustomContext.Add(new VoipHeader("Foo-1", "Bar")); //no prefix
```

Then SDK will send below payload to PMA:
```
customContext: {        
        "voipHeaders":
        {
                "Foo-1": "Bar"
        }
}
```
### Describe the problem that is addressed by this PR


### What are the possible designs available to address the problem? If
there are more than one possible design, why was the one in this PR
chosen?


### Are there test cases added in this PR? _(If not, why?)_


### Provide a list of related PRs _(if any)_


### Command used to generate this PR:**_(Applicable only to SDK release
request PRs)_

### Checklists
- [ ] Added impacted package name to the issue description
- [ ] Does this PR needs any fixes in the SDK Generator?** _(If so,
create an Issue in the
[Autorest/typescript](https://github.com/Azure/autorest.typescript)
repository and link it here)_
- [ ] Added a changelog (if necessary)

Author: fangchen0601

sdk/communication/communication-call-automation/review/communication-call-automation.api.md

@@ -133,16 +133,11 @@ export interface CallDisconnected extends Omit<RestCallDisconnected, "callConnec
 
 // @public
 export interface CallInvite {
-    readonly sipHeaders?: {
-        [propertyName: string]: string;
-    };
+    customContext?: CustomContext;
     readonly sourceCallIdNumber?: PhoneNumberIdentifier;
     // (undocumented)
     sourceDisplayName?: string;
     readonly targetParticipant: PhoneNumberIdentifier | CommunicationUserIdentifier;
-    readonly voipHeaders?: {
-        [propertyName: string]: string;
-    };
 }
 
 // @public
@@ -314,21 +309,33 @@ export interface ContinuousDtmfRecognitionToneReceived extends Omit<RestContinuo
 // @public
 export interface CreateCallOptions extends OperationOptions {
     azureCognitiveServicesEndpointUrl?: string;
+    customContext?: CustomContext;
     mediaStreamingConfiguration?: MediaStreamingConfiguration;
     operationContext?: string;
-    sipHeaders?: {
-        [propertyName: string]: string;
-    };
     sourceCallIdNumber?: PhoneNumberIdentifier;
     sourceDisplayName?: string;
-    voipHeaders?: {
-        [propertyName: string]: string;
-    };
 }
 
 // @public
 export type CreateCallResult = CallResult;
 
+// @public
+export class CustomContext {
+    constructor(sipHeaders: {
+        [key: string]: string;
+    }, voipHeaders: {
+        [key: string]: string;
+    });
+    // Warning: (ae-forgotten-export) The symbol "CustomContextHeader" needs to be exported by the entry point index.d.ts
+    add(header: CustomContextHeader): void;
+    sipHeaders: {
+        [key: string]: string;
+    };
+    voipHeaders: {
+        [key: string]: string;
+    };
+}
+
 // @public
 export type DeleteRecordingOptions = OperationOptions;
 
@@ -862,6 +869,24 @@ export interface SendDtmfOptions extends OperationOptions {
     operationContext?: string;
 }
 
+// @public
+export interface SIPCustomHeader extends CustomContextHeader {
+}
+
+// @public
+export class SIPCustomHeader implements CustomContextHeader {
+    constructor(key: string, value: string);
+}
+
+// @public
+export interface SIPUserToUserHeader extends CustomContextHeader {
+}
+
+// @public
+export class SIPUserToUserHeader implements CustomContextHeader {
+    constructor(value: string);
+}
+
 // @public
 export interface SsmlSource extends PlaySource {
     // (undocumented)
@@ -916,14 +941,18 @@ export interface TransferCallResult {
 // @public
 export interface TransferCallToParticipantOptions extends OperationOptions {
     callbackUrlOverride?: string;
+    customContext?: CustomContext;
     operationContext?: string;
-    sipHeaders?: {
-        [propertyName: string]: string;
-    };
     transferee?: CommunicationIdentifier;
-    voipHeaders?: {
-        [propertyName: string]: string;
-    };
+}
+
+// @public
+export interface VoipHeader extends CustomContextHeader {
+}
+
+// @public
+export class VoipHeader implements CustomContextHeader {
+    constructor(key: string, value: string);
 }
 
 // (No @packageDocumentation comment for this package)

sdk/communication/communication-call-automation/src/callAutomationClient.ts

@@ -231,8 +231,8 @@ export class CallAutomationClient {
       azureCognitiveServicesEndpointUrl: options.azureCognitiveServicesEndpointUrl,
       mediaStreamingConfiguration: options.mediaStreamingConfiguration,
       customContext: {
-        sipHeaders: targetParticipant.sipHeaders,
-        voipHeaders: targetParticipant.voipHeaders,
+        sipHeaders: targetParticipant.customContext?.sipHeaders,
+        voipHeaders: targetParticipant.customContext?.voipHeaders,
       },
       sourceCallerIdNumber: PhoneNumberIdentifierModelConverter(
         targetParticipant.sourceCallIdNumber
@@ -262,8 +262,8 @@ export class CallAutomationClient {
       azureCognitiveServicesEndpointUrl: options.azureCognitiveServicesEndpointUrl,
       mediaStreamingConfiguration: options.mediaStreamingConfiguration,
       customContext: {
-        sipHeaders: options.sipHeaders,
-        voipHeaders: options.voipHeaders,
+        sipHeaders: options.customContext?.sipHeaders,
+        voipHeaders: options.customContext?.voipHeaders,
       },
       sourceCallerIdNumber: PhoneNumberIdentifierModelConverter(options.sourceCallIdNumber),
       sourceDisplayName: options.sourceDisplayName,
@@ -355,8 +355,9 @@ export class CallAutomationClient {
       incomingCallContext: incomingCallContext,
       target: communicationIdentifierModelConverter(targetParticipant.targetParticipant),
       customContext: {
-        sipHeaders: targetParticipant.sipHeaders ?? options.sipHeaders ?? undefined,
-        voipHeaders: targetParticipant.voipHeaders ?? options.voipHeaders ?? undefined,
+        sipHeaders: targetParticipant.customContext?.sipHeaders ?? options.sipHeaders ?? undefined,
+        voipHeaders:
+          targetParticipant.customContext?.voipHeaders ?? options.voipHeaders ?? undefined,
       },
     };
     const optionsInternal = {

sdk/communication/communication-call-automation/src/callConnection.ts

@@ -183,8 +183,8 @@ export class CallConnection {
       invitationTimeoutInSeconds: options.invitationTimeoutInSeconds,
       operationContext: options.operationContext,
       customContext: {
-        sipHeaders: targetParticipant.sipHeaders,
-        voipHeaders: targetParticipant.voipHeaders,
+        sipHeaders: targetParticipant.customContext?.sipHeaders,
+        voipHeaders: targetParticipant.customContext?.voipHeaders,
       },
       callbackUriOverride: options.callbackUrlOverride,
     };
@@ -223,8 +223,8 @@ export class CallConnection {
       targetParticipant: communicationIdentifierModelConverter(targetParticipant),
       operationContext: options.operationContext,
       customContext: {
-        sipHeaders: options.sipHeaders,
-        voipHeaders: options.voipHeaders,
+        sipHeaders: options.customContext?.sipHeaders,
+        voipHeaders: options.customContext?.voipHeaders,
       },
       callbackUriOverride: options.callbackUrlOverride,
       transferee: options.transferee && communicationIdentifierModelConverter(options.transferee),

sdk/communication/communication-call-automation/src/models/models.ts

@@ -153,17 +153,92 @@ export enum RecognizeInputType {
   Choices = "choices",
 }
 
+interface CustomContextHeader {
+  key: string;
+  value: string;
+}
+
+/** SIPCustomHeader */
+export interface SIPCustomHeader extends CustomContextHeader {}
+
+/** SIPUserToUserHeader */
+export interface SIPUserToUserHeader extends CustomContextHeader {}
+
+/** VoipHeader */
+export interface VoipHeader extends CustomContextHeader {}
+
+/** Custom Context SIP header */
+export class SIPCustomHeader implements CustomContextHeader {
+  // Create a new SIP custom header.
+  constructor(key: string, value: string) {
+    this.key = "X-MS-Custom-" + key;
+    this.value = value;
+  }
+}
+
+/** Custom Context SIP User-to-User header */
+export class SIPUserToUserHeader implements CustomContextHeader {
+  // Create a new SIP UUI header.
+  constructor(value: string) {
+    this.key = "User-to-User";
+    this.value = value;
+  }
+}
+
+/** Custom Context VOIP header */
+export class VoipHeader implements CustomContextHeader {
+  constructor(key: string, value: string) {
+    this.key = key;
+    this.value = value;
+  }
+}
+
+/** Custom Context */
+export class CustomContext {
+  /** Dictionary of VOIP headers. */
+  public voipHeaders: { [key: string]: string };
+
+  /** Dictionary of SIP headers. */
+  public sipHeaders: { [key: string]: string };
+
+  // Creates a new CustomContext.
+  constructor(sipHeaders: { [key: string]: string }, voipHeaders: { [key: string]: string }) {
+    this.sipHeaders = sipHeaders;
+    this.voipHeaders = voipHeaders;
+  }
+
+  /** Add a custom context sip or voip header. */
+  public add(header: CustomContextHeader): void {
+    if (header instanceof SIPUserToUserHeader) {
+      if (this.sipHeaders == null) {
+        throw new Error("Cannot add sip header, SipHeaders is null.");
+      }
+      this.sipHeaders[header.key] = header.value;
+    } else if (header instanceof SIPCustomHeader) {
+      if (this.sipHeaders == null) {
+        throw new Error("Cannot add sip header, SipHeaders is null.");
+      }
+      this.sipHeaders[header.key] = header.value;
+    } else if (header instanceof VoipHeader) {
+      if (this.voipHeaders == null) {
+        throw new Error("Cannot add voip header, VoipHeaders is null");
+      }
+      this.voipHeaders[header.key] = header.value;
+    } else {
+      throw new Error("Unknown custom context header type.");
+    }
+  }
+}
+
 /** Call invitee details. */
 export interface CallInvite {
   /** The Target's PhoneNumberIdentifier or CommunicationUserIdentifier. */
   readonly targetParticipant: PhoneNumberIdentifier | CommunicationUserIdentifier;
   /** Caller's phone number identifier. */
   readonly sourceCallIdNumber?: PhoneNumberIdentifier;
   sourceDisplayName?: string;
-  /** Custom context for PSTN. */
-  readonly sipHeaders?: { [propertyName: string]: string };
-  /** Custom context for voipr. */
-  readonly voipHeaders?: { [propertyName: string]: string };
+  /** The Custom Context. */
+  customContext?: CustomContext;
 }
 
 /** The locator type of a call. */

sdk/communication/communication-call-automation/src/models/options.ts

@@ -16,6 +16,7 @@ import {
   RecordingFormat,
   CallLocator,
   ChannelAffinity,
+  CustomContext,
 } from "./models";
 
 /** Options to configure the recognize operation. */
@@ -80,10 +81,8 @@ export interface CreateCallOptions extends OperationOptions {
   azureCognitiveServicesEndpointUrl?: string;
   /** Configuration of Media streaming. */
   mediaStreamingConfiguration?: MediaStreamingConfiguration;
-  /** Headers for SIP calls */
-  sipHeaders?: { [propertyName: string]: string };
-  /** Headers for VOIP calls */
-  voipHeaders?: { [propertyName: string]: string };
+  /** The Custom Context. */
+  customContext?: CustomContext;
 }
 
 /**
@@ -122,10 +121,8 @@ export interface RejectCallOptions extends OperationOptions {
 export interface TransferCallToParticipantOptions extends OperationOptions {
   /** Used by customers when calling mid-call actions to correlate the request to the response event. */
   operationContext?: string;
-  /** Custom context for PSTN. */
-  sipHeaders?: { [propertyName: string]: string };
-  /** Custom context for voip. */
-  voipHeaders?: { [propertyName: string]: string };
+  /** The Custom Context. */
+  customContext?: CustomContext;
   /** Call back URI override for this request */
   callbackUrlOverride?: string;
   /** Participant that is being transferred away */