[communication-common] Add options bag for getToken function, mark @hidden where applicable (Azure#14046)

* [communication-common] Add options bag for getToken function, mark @hidden where applicable

* rename url to endpoint in CommunicationIdentityClient constructor

Author: DominikMe

sdk/communication/communication-chat/src/credential/communicationTokenCredentialPolicy.ts

@@ -14,7 +14,7 @@ export const createCommunicationTokenCredentialPolicy = (
 ): RequestPolicyFactory => {
   return bearerTokenAuthenticationPolicy(
     {
-      getToken: (_scopes, options) => credential.getToken(options?.abortSignal)
+      getToken: (_scopes, options) => credential.getToken({ abortSignal: options?.abortSignal })
     },
     []
   );

sdk/communication/communication-chat/src/signaling/signalingClient.browser.ts

@@ -1,13 +1,34 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import { CommunicationSignalingClient, SignalingClient } from "@azure/communication-signaling";
+import {
+  CommunicationSignalingClient,
+  CommunicationUserCredential,
+  SignalingClient
+} from "@azure/communication-signaling";
 import { CommunicationTokenCredential } from "@azure/communication-common";
 import { AzureLogger } from "@azure/logger";
+import { AbortSignalLike, AccessToken } from "@azure/core-http";
 
 export const getSignalingClient = (
   credential: CommunicationTokenCredential,
   logger: AzureLogger
 ): SignalingClient | undefined => {
-  return new CommunicationSignalingClient(credential, logger);
+  return new CommunicationSignalingClient(new SignalingCredentialType(credential), logger);
 };
+
+/**
+ * Bridge credential until @azure/communication-signaling has been updated
+ * to match common's CommunicationTokenCredential interface.
+ */
+class SignalingCredentialType implements CommunicationUserCredential {
+  constructor(private credential: CommunicationTokenCredential) {}
+
+  getToken(abortSignal?: AbortSignalLike): Promise<AccessToken> {
+    return this.credential.getToken({ abortSignal });
+  }
+
+  dispose() {
+    this.credential.dispose();
+  }
+}

sdk/communication/communication-common/CHANGELOG.md

@@ -2,7 +2,6 @@
 
 ## 1.0.0-beta.6 (Unreleased)
 
-
 ## 1.0.0-beta.5 (2021-02-09)
 
 ### Breaking Changes
@@ -11,6 +10,7 @@
 - Removed `id` from `CommunicationUserIdentifier`.
 - Renamed `id` to `rawId` in `PhoneNumberIdentifier`.
 - Renamed `id` to `rawId` in `MicrosoftTeamsUserIdentifier`.
+- Replaced `abortSignal?` argument in `CommunicationTokenCredential.getToken` with `options?: CommunicationGetTokenOptions`.
 
 ## 1.0.0-beta.4 (2021-01-25)
 

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

@@ -15,9 +15,14 @@ export class AzureCommunicationTokenCredential implements CommunicationTokenCred
     constructor(token: string);
     constructor(refreshOptions: CommunicationTokenRefreshOptions);
     dispose(): void;
-    getToken(abortSignal?: AbortSignalLike): Promise<AccessToken>;
+    getToken(options?: CommunicationGetTokenOptions): Promise<AccessToken>;
     }
 
+// @public
+export interface CommunicationGetTokenOptions {
+    abortSignal?: AbortSignalLike;
+}
+
 // @public
 export type CommunicationIdentifier = CommunicationUserIdentifier | PhoneNumberIdentifier | MicrosoftTeamsUserIdentifier | UnknownIdentifier;
 
@@ -27,7 +32,7 @@ export type CommunicationIdentifierKind = CommunicationUserKind | PhoneNumberKin
 // @public
 export interface CommunicationTokenCredential {
     dispose(): void;
-    getToken(abortSignal?: AbortSignalLike): Promise<AccessToken>;
+    getToken(options?: CommunicationGetTokenOptions): Promise<AccessToken>;
 }
 
 // @public
@@ -53,8 +58,8 @@ export const createCommunicationAccessKeyCredentialPolicy: (credential: KeyCrede
 // @public
 export const createCommunicationAuthPolicy: (credential: KeyCredential | TokenCredential) => RequestPolicyFactory;
 
-// @internal
-export const _deserializeCommunicationIdentifier: (serializedIdentifier: _SerializedCommunicationIdentifier) => CommunicationIdentifierKind;
+// @public
+export const deserializeCommunicationIdentifier: (serializedIdentifier: SerializedCommunicationIdentifier) => CommunicationIdentifierKind;
 
 // @public
 export interface EndpointCredential {
@@ -110,34 +115,34 @@ export interface PhoneNumberKind extends PhoneNumberIdentifier {
     kind: "phoneNumber";
 }
 
-// @internal
-export const _serializeCommunicationIdentifier: (identifier: CommunicationIdentifier) => _SerializedCommunicationIdentifier;
+// @public
+export const serializeCommunicationIdentifier: (identifier: CommunicationIdentifier) => SerializedCommunicationIdentifier;
 
-// @internal
-export type _SerializedCommunicationCloudEnvironment = "public" | "dod" | "gcch";
+// @public
+export type SerializedCommunicationCloudEnvironment = "public" | "dod" | "gcch";
 
-// @internal
-export interface _SerializedCommunicationIdentifier {
-    communicationUser?: _SerializedCommunicationUserIdentifier;
-    microsoftTeamsUser?: _SerializedMicrosoftTeamsUserIdentifier;
-    phoneNumber?: _SerializedPhoneNumberIdentifier;
+// @public
+export interface SerializedCommunicationIdentifier {
+    communicationUser?: SerializedCommunicationUserIdentifier;
+    microsoftTeamsUser?: SerializedMicrosoftTeamsUserIdentifier;
+    phoneNumber?: SerializedPhoneNumberIdentifier;
     rawId?: string;
 }
 
-// @internal
-export interface _SerializedCommunicationUserIdentifier {
+// @public
+export interface SerializedCommunicationUserIdentifier {
     id: string;
 }
 
-// @internal
-export interface _SerializedMicrosoftTeamsUserIdentifier {
-    cloud?: _SerializedCommunicationCloudEnvironment;
+// @public
+export interface SerializedMicrosoftTeamsUserIdentifier {
+    cloud?: SerializedCommunicationCloudEnvironment;
     isAnonymous?: boolean;
     userId: string;
 }
 
-// @internal
-export interface _SerializedPhoneNumberIdentifier {
+// @public
+export interface SerializedPhoneNumberIdentifier {
     value: string;
 }
 

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

@@ -3,7 +3,7 @@
 
 import { AbortSignalLike, AccessToken } from "@azure/core-http";
 import { parseToken } from "./tokenParser";
-import { TokenCredential } from "./communicationTokenCredential";
+import { TokenCredential, CommunicationGetTokenOptions } from "./communicationTokenCredential";
 
 /**
  * Options for auto-refreshing a Communication Token credential.
@@ -53,12 +53,12 @@ export class AutoRefreshTokenCredential implements TokenCredential {
     }
   }
 
-  public async getToken(abortSignal?: AbortSignalLike): Promise<AccessToken> {
+  public async getToken(options?: CommunicationGetTokenOptions): Promise<AccessToken> {
     if (!this.isCurrentTokenExpiringSoon) {
       return this.currentToken;
     }
 
-    const updatePromise = this.updateTokenAndReschedule(abortSignal);
+    const updatePromise = this.updateTokenAndReschedule(options?.abortSignal);
 
     if (!this.isCurrentTokenValid) {
       await updatePromise;

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

@@ -11,15 +11,25 @@ import {
 
 export type TokenCredential = Pick<AzureCommunicationTokenCredential, "getToken" | "dispose">;
 
+/**
+ * Options for `CommunicationTokenCredential`'s `getToken` function.
+ */
+export interface CommunicationGetTokenOptions {
+  /**
+   * An implementation of `AbortSignalLike` to cancel the operation.
+   */
+  abortSignal?: AbortSignalLike;
+}
+
 /**
  * The Azure Communication Services token credential.
  */
 export interface CommunicationTokenCredential {
   /**
    * Gets an `AccessToken` for the user. Throws if already disposed.
-   * @param abortSignal - An implementation of `AbortSignalLike` to cancel the operation.
+   * @param options - Additional options.
    */
-  getToken(abortSignal?: AbortSignalLike): Promise<AccessToken>;
+  getToken(options?: CommunicationGetTokenOptions): Promise<AccessToken>;
   /**
    * Disposes the CommunicationTokenCredential and cancels any internal auto-refresh operation.
    */
@@ -56,9 +66,9 @@ export class AzureCommunicationTokenCredential implements CommunicationTokenCred
    * Gets an `AccessToken` for the user. Throws if already disposed.
    * @param abortSignal - An implementation of `AbortSignalLike` to cancel the operation.
    */
-  public async getToken(abortSignal?: AbortSignalLike): Promise<AccessToken> {
+  public async getToken(options?: CommunicationGetTokenOptions): Promise<AccessToken> {
     this.throwIfDisposed();
-    const token = await this.tokenCredential.getToken(abortSignal);
+    const token = await this.tokenCredential.getToken(options);
     this.throwIfDisposed();
     return token;
   }

sdk/communication/communication-common/src/credential/clientArguments.ts

@@ -41,6 +41,7 @@ export const isKeyCredential = (credential: unknown): credential is KeyCredentia
 
 /**
  * The URL and credential from parsing the arguments of a communication client.
+ * @hidden
  */
 export type UrlWithCredential = {
   url: string;
@@ -49,6 +50,7 @@ export type UrlWithCredential = {
 
 /**
  * Parses arguments passed to a communication client.
+ * @hidden
  */
 export const parseClientArguments = (
   connectionStringOrUrl: string,

sdk/communication/communication-common/src/credential/communicationAccessKeyCredentialPolicy.ts

@@ -16,10 +16,10 @@ import {
 import { shaHash, shaHMAC } from "./cryptoUtils";
 
 /**
- * Creates an HTTP pipeline policy to authenticate a request
- * using an `KeyCredential`
+ * Creates an HTTP pipeline policy to authenticate a request using a `KeyCredential`.
+ * @hidden
  *
- * @param credential - The key credential
+ * @param credential - The key credential.
  */
 export const createCommunicationAccessKeyCredentialPolicy = (
   credential: KeyCredential

sdk/communication/communication-common/src/credential/communicationAuthPolicy.ts

@@ -6,9 +6,10 @@ import { bearerTokenAuthenticationPolicy, RequestPolicyFactory } from "@azure/co
 import { createCommunicationAccessKeyCredentialPolicy } from "./communicationAccessKeyCredentialPolicy";
 /**
  * Creates a pipeline policy to authenticate request based
- * on the credential passed in
+ * on the credential passed in.
+ * @hidden
  *
- * @param credential - The key credential
+ * @param credential - The KeyCredential or TokenCredential.
  */
 export const createCommunicationAuthPolicy = (
   credential: KeyCredential | TokenCredential

sdk/communication/communication-common/src/credential/connectionString.ts

@@ -4,7 +4,8 @@
 import { AzureKeyCredential, KeyCredential } from "@azure/core-auth";
 /**
  * Represents different properties of connection string
- * using format "/endpoint=(.*);accesskey=(.*)"
+ * using format "/endpoint=(.*);accesskey=(.*)".
+ * @hidden
  */
 export interface EndpointCredential {
   /**
@@ -28,7 +29,8 @@ const tryParseConnectionString = (s: string): EndpointCredential | undefined =>
   return undefined;
 };
 /**
- * Returns an EndpointCredential to easily access properties of the connection string
+ * Returns an EndpointCredential to easily access properties of the connection string.
+ * @hidden
  *
  * @param connectionString - The connection string to parse
  * @returns Object to access the endpoint and the credenials