Merge remote-tracking branch 'upstream/next/release' into cognito-cache

packages/analytics/src/index.ts

@@ -1,5 +1,10 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-export * from './providers/pinpoint';
+export {
+	record,
+	identifyUser,
+	RecordInput,
+	IdentifyUserInput,
+} from './providers/pinpoint';
 export { AnalyticsError } from './errors';

packages/analytics/src/providers/pinpoint/apis/identifyUser.ts

@@ -5,21 +5,56 @@ import { AnalyticsAction } from '@aws-amplify/core/internals/utils';
 import { updateEndpoint } from '@aws-amplify/core/internals/providers/pinpoint';
 import { AnalyticsValidationErrorCode } from '../../../errors';
 import { getAnalyticsUserAgentString } from '../../../utils/userAgent';
-import { IdentifyUserParameters, UpdateEndpointException } from '../types';
+import { IdentifyUserInput, UpdateEndpointException } from '../types';
 import { resolveConfig, resolveCredentials } from '../utils';
 
 /**
- * Identifies the current user with Pinpoint.
+ * Sends information about a user to Pinpoint. Sending user information allows you to associate a user to their user
+ * profile and activities or actions in your application. Activity can be tracked across devices & platforms by using
+ * the same `userId`.
  *
- * @param {IdentifyUserParameters} params parameters used to construct requests sent to Pinpoint's UpdateEndpoint API.
+ * @param {IdentifyUserParameters} params The input object used to construct requests sent to Pinpoint's UpdateEndpoint
+ *  API.
  *
- * @throws An {@link UpdateEndpointException} when the underlying Pinpoint service returns an error.
- * @throws An {@link AnalyticsValidationErrorCode} when API call parameters are invalid.
+ * @throws service: {@link UpdateEndpointException} - Thrown when the underlying Pinpoint service returns an error.
+ * @throws validation: {@link AnalyticsValidationErrorCode} - Thrown when the provided parameters or library
+ *  configuration is incorrect.
+ *
+ * @returns A promise that will resolve when the operation is complete.
+ *
+ * @example
+ * ```ts
+ * // Identify a user with Pinpoint
+ * await identifyUser({
+ *     userId,
+ *     userProfile: {
+ *         attributes: {
+ *             email: [userEmail],
+ *         },
+ *     }
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Identify a user with Pinpoint with some additional demographics
+ * await identifyUser({
+ *     userId,
+ *     userProfile: {
+ *         attributes: {
+ *             email: [userEmail],
+ *         },
+ *         demographic: {
+ *             platform: 'ios',
+ *             timezone: 'America/Los_Angeles'
+ *         }
+ *     }
+ * });
  */
 export const identifyUser = async ({
 	userId,
 	userProfile,
-}: IdentifyUserParameters): Promise<void> => {
+}: IdentifyUserInput): Promise<void> => {
 	const { credentials, identityId } = await resolveCredentials();
 	const { appId, region } = resolveConfig();
 	updateEndpoint({

packages/analytics/src/providers/pinpoint/apis/record.ts

@@ -11,21 +11,46 @@ import {
 	assertValidationError,
 } from '../../../errors';
 import { getAnalyticsUserAgentString } from '../../../utils/userAgent';
-import { RecordParameters } from '../types/parameters';
+import { RecordInput } from '../types';
 import { resolveConfig, resolveCredentials } from '../utils';
 
 const logger = new Logger('Analytics');
 
 /**
- * Sends an event to Pinpoint.
+ * Records an Analytic event to Pinpoint. Events will be buffered and periodically sent to Pinpoint.
  *
- * @param {RecordParameters} params Parameters used to construct the request.
+ * @param {RecordInput} params The input object used to construct the request.
  *
- * @throws An {@link AnalyticsValidationErrorCode} when there is an error in the parameters or configuration.
+ * @throws validation: {@link AnalyticsValidationErrorCode} - Thrown when the provided parameters or library
+ *  configuration is incorrect.
  *
- * @returns A promise that will resolve when the request is complete.
+ * @example
+ * ```ts
+ * // Send an event to Pinpoint
+ * record({
+ *     event: {
+ * 	       name: eventName,
+ *     }
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Send an event to Pinpoint with metrics & custom attributes
+ * record({
+ *     event: {
+ *         name: eventName,
+ *         attributes: {
+ *             'my-attribute': attributeValue
+ *         },
+ *         metrics: {
+ *             'my-metric': metricValue
+ *         }
+ *     }
+ * })
+ * ```
  */
-export const record = ({ event }: RecordParameters): void => {
+export const record = ({ event }: RecordInput): void => {
 	const { appId, region } = resolveConfig();
 
 	assertValidationError(!!event, AnalyticsValidationErrorCode.NoEvent);

packages/analytics/src/providers/pinpoint/index.ts

@@ -1,4 +1,5 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-export * from './apis';
+export { record, identifyUser } from './apis';
+export { RecordInput, IdentifyUserInput } from './types/inputs';

packages/analytics/src/providers/pinpoint/types/index.ts

@@ -2,4 +2,4 @@
 // SPDX-License-Identifier: Apache-2.0
 
 export { UpdateEndpointException } from './errors';
-export { IdentifyUserParameters } from './parameters';
+export { RecordInput, IdentifyUserInput } from './inputs';

packages/analytics/src/providers/pinpoint/types/parameters.ts → packages/analytics/src/providers/pinpoint/types/inputs.ts

@@ -4,14 +4,14 @@
 import { UserProfile } from '@aws-amplify/core';
 import { PinpointAnalyticsEvent } from '@aws-amplify/core/internals/providers/pinpoint';
 
-export type RecordParameters = {
+export type RecordInput = {
 	/**
 	 * An event to send to the default Analytics provider.
 	 */
 	event: PinpointAnalyticsEvent;
 };
 
-export type IdentifyUserParameters = {
+export type IdentifyUserInput = {
 	/**
 	 * A User ID associated to the current device.
 	 */

packages/core/src/providers/pinpoint/apis/record.ts

@@ -2,9 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { v4 as uuid } from 'uuid';
-import { PinpointRecordParameters, PinpointSession } from '../types';
+import { PinpointRecordInput, PinpointSession } from '../types';
 import { getEndpointId } from '../utils';
-import { 
+import {
 	BUFFER_SIZE,
 	FLUSH_INTERVAL,
 	FLUSH_SIZE,
@@ -28,11 +28,11 @@ export const record = async ({
 	identityId,
 	region,
 	userAgentValue,
-}: PinpointRecordParameters): Promise<void> => {
+}: PinpointRecordInput): Promise<void> => {
 	const timestampISOString = new Date().toISOString();
 	const eventId = uuid();
 	let endpointId = await getEndpointId(appId, category);
-  
+
 	// Prepare event buffer if required
 	const buffer = getEventBuffer({
 		appId,
@@ -43,7 +43,7 @@ export const record = async ({
 		identityId,
 		region,
 		resendLimit: RESEND_LIMIT,
-		userAgentValue
+		userAgentValue,
 	});
 
 	// Prepare a Pinpoint endpoint via updateEndpoint if one does not already exist, which will generate and cache an
@@ -64,7 +64,7 @@ export const record = async ({
 	if (!endpointId) {
 		throw new AmplifyError({
 			name: 'ENDPOINT_NOT_CREATED',
-			message: 'Endpoint was not created.'
+			message: 'Endpoint was not created.',
 		});
 	}
 
@@ -77,14 +77,14 @@ export const record = async ({
 			StartTimestamp: timestampISOString,
 		};
 	}
-  
+
 	// Push event to buffer
 	buffer.push({
 		eventId,
 		endpointId,
 		event,
 		session,
 		timestamp: timestampISOString,
-		resendLimit: RESEND_LIMIT
+		resendLimit: RESEND_LIMIT,
 	});
 };

packages/core/src/providers/pinpoint/apis/updateEndpoint.ts

@@ -7,7 +7,7 @@ import {
 	updateEndpoint as clientUpdateEndpoint,
 	UpdateEndpointInput,
 } from '../../../AwsClients/Pinpoint';
-import { PinpointUpdateEndpointParameters } from '../types';
+import { PinpointUpdateEndpointInput } from '../types';
 import { cacheEndpointId, getEndpointId } from '../utils';
 
 /**
@@ -25,7 +25,7 @@ export const updateEndpoint = async ({
 	userId,
 	userProfile,
 	userAgentValue,
-}: PinpointUpdateEndpointParameters): Promise<void> => {
+}: PinpointUpdateEndpointInput): Promise<void> => {
 	const endpointId = await getEndpointId(appId, category);
 	// only generate a new endpoint id if one was not found in cache
 	const createdEndpointId = !endpointId ? uuidv4() : undefined;

packages/core/src/providers/pinpoint/types/pinpoint.ts

@@ -44,13 +44,13 @@ type PinpointCommonParameters = {
 	userAgentValue?: string;
 };
 
-export type PinpointUpdateEndpointParameters = PinpointCommonParameters &
+export type PinpointUpdateEndpointInput = PinpointCommonParameters &
 	PinpointServiceOptions & {
 		channelType?: SupportedChannelType;
 		userId?: string;
 		userProfile?: UserProfile;
 	};
 
-export type PinpointRecordParameters = PinpointCommonParameters & {
+export type PinpointRecordInput = PinpointCommonParameters & {
 	event: PinpointAnalyticsEvent;
 };