@aws-amplify/analytics 7.0.1-preview-testing.034e780.0 → 7.0.1-server-generate-client.1e317a1.0

package/src/trackers/SessionTracker.native.ts

@@ -0,0 +1,106 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	sessionListener,
+	SessionState,
+} from '@aws-amplify/core/internals/utils';
+import { ConsoleLogger } from '@aws-amplify/core';
+import {
+	SessionTrackingOptions,
+	TrackerEventRecorder,
+	TrackerInterface,
+} from '../types/trackers';
+
+const SESSION_START_EVENT = '_session.start';
+const SESSION_STOP_EVENT = '_session.stop';
+
+const logger = new ConsoleLogger('SessionTracker');
+
+export class SessionTracker implements TrackerInterface {
+	private options: SessionTrackingOptions;
+	private eventRecorder: TrackerEventRecorder;
+	private initialEventSent: boolean;
+	private sessionTrackingActive: boolean;
+
+	constructor(
+		eventRecorder: TrackerEventRecorder,
+		options?: SessionTrackingOptions
+	) {
+		this.options = {};
+		this.eventRecorder = eventRecorder;
+		this.initialEventSent = false;
+		this.sessionTrackingActive = false;
+		this.handleStateChange = this.handleStateChange.bind(this);
+
+		this.configure(eventRecorder, options);
+	}
+
+	public configure(
+		eventRecorder: TrackerEventRecorder,
+		options?: SessionTrackingOptions
+	) {
+		this.eventRecorder = eventRecorder;
+
+		// Clean up any existing listeners
+		this.cleanup();
+
+		// Apply defaults
+		this.options = {
+			attributes: options?.attributes ?? {},
+		};
+
+		// Setup state listeners
+		if (!this.sessionTrackingActive) {
+			sessionListener.addStateChangeListener(
+				this.handleStateChange,
+				!this.initialEventSent
+			);
+
+			this.sessionTrackingActive = true;
+		}
+	}
+
+	public cleanup() {
+		if (this.sessionTrackingActive) {
+			sessionListener.removeStateChangeListener(this.handleStateChange);
+		}
+
+		this.sessionTrackingActive = false;
+	}
+
+	private handleStateChange(state: SessionState) {
+		if (state === 'started') {
+			this.sessionStarted();
+		} else {
+			this.sessionStopped();
+		}
+	}
+
+	private sessionStarted() {
+		const attributes = this.options.attributes ?? {};
+
+		logger.debug('Recording automatically tracked page view event', {
+			SESSION_START_EVENT,
+			attributes,
+		});
+
+		this.eventRecorder(SESSION_START_EVENT, attributes);
+
+		// NOTE: The initial event will not be re-sent on re-configuration (e.g. to add additional custom attributes)
+		if (!this.initialEventSent) {
+			this.initialEventSent = true;
+		}
+	}
+
+	private sessionStopped() {
+		const attributes = this.options.attributes ?? {};
+
+		logger.debug('Recording automatically tracked page view event', {
+			SESSION_STOP_EVENT,
+			attributes,
+		});
+
+		this.eventRecorder(SESSION_STOP_EVENT, attributes);
+	}
+}

package/src/trackers/SessionTracker.ts

@@ -0,0 +1,106 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	sessionListener,
+	SessionState,
+} from '@aws-amplify/core/internals/utils';
+import { ConsoleLogger } from '@aws-amplify/core';
+import {
+	SessionTrackingOptions,
+	TrackerEventRecorder,
+	TrackerInterface,
+} from '../types/trackers';
+
+const SESSION_START_EVENT = '_session.start';
+const SESSION_STOP_EVENT = '_session.stop';
+
+const logger = new ConsoleLogger('SessionTracker');
+
+export class SessionTracker implements TrackerInterface {
+	private options: SessionTrackingOptions;
+	private eventRecorder: TrackerEventRecorder;
+	private sessionTrackingActive: boolean;
+	private initialEventSent: boolean;
+
+	constructor(
+		eventRecorder: TrackerEventRecorder,
+		options?: SessionTrackingOptions
+	) {
+		this.options = {};
+		this.eventRecorder = eventRecorder;
+		this.sessionTrackingActive = false;
+		this.initialEventSent = false;
+		this.handleStateChange = this.handleStateChange.bind(this);
+
+		this.configure(eventRecorder, options);
+	}
+
+	public configure(
+		eventRecorder: TrackerEventRecorder,
+		options?: SessionTrackingOptions
+	) {
+		this.eventRecorder = eventRecorder;
+
+		// Clean up any existing listeners
+		this.cleanup();
+
+		// Apply defaults
+		this.options = {
+			attributes: options?.attributes ?? {},
+		};
+
+		// Setup state listeners
+		if (!this.sessionTrackingActive) {
+			sessionListener.addStateChangeListener(
+				this.handleStateChange,
+				!this.initialEventSent
+			);
+
+			this.sessionTrackingActive = true;
+		}
+	}
+
+	public cleanup() {
+		if (this.sessionTrackingActive) {
+			sessionListener.removeStateChangeListener(this.handleStateChange);
+		}
+
+		this.sessionTrackingActive = false;
+	}
+
+	private handleStateChange(state: SessionState) {
+		if (state === 'started') {
+			this.sessionStarted();
+		} else {
+			this.sessionStopped();
+		}
+	}
+
+	private sessionStarted() {
+		const attributes = this.options.attributes ?? {};
+
+		logger.debug('Recording automatically tracked page view event', {
+			SESSION_START_EVENT,
+			attributes,
+		});
+
+		this.eventRecorder(SESSION_START_EVENT, attributes);
+
+		// NOTE: The initial event will not be re-sent on re-configuration (e.g. to add additional custom attributes)
+		if (!this.initialEventSent) {
+			this.initialEventSent = true;
+		}
+	}
+
+	private sessionStopped() {
+		const attributes = this.options.attributes ?? {};
+
+		logger.debug('Recording automatically tracked page view event', {
+			SESSION_STOP_EVENT,
+			attributes,
+		});
+
+		this.eventRecorder(SESSION_STOP_EVENT, attributes);
+	}
+}

package/src/trackers/index.ts

@@ -0,0 +1,6 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { EventTracker } from './EventTracker';
+export { PageViewTracker } from './PageViewTracker';
+export { SessionTracker } from './SessionTracker';

package/src/types/index.ts

@@ -1,4 +1,11 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-export * from './analytics';
+export { AnalyticsServiceOptions } from './options';
+
+export {
+	AnalyticsConfigureAutoTrackInput,
+	AnalyticsIdentifyUserInput,
+} from './inputs';
+
+export { KinesisStream, KinesisShard, KinesisEventData } from './kinesis';

package/src/types/inputs.ts

@@ -0,0 +1,52 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { UserProfile } from '@aws-amplify/core';
+import { AnalyticsServiceOptions } from '.';
+import {
+	SessionTrackingOptions,
+	PageViewTrackingOptions,
+	EventTrackingOptions,
+} from './trackers';
+
+/**
+ * Input type for `identifyUser`.
+ */
+export type AnalyticsIdentifyUserInput<
+	ServiceOptions extends AnalyticsServiceOptions = AnalyticsServiceOptions
+> = {
+	/**
+	 * A User ID associated to the current device.
+	 */
+	userId: string;
+
+	/**
+	 * Additional information about the user and their device.
+	 */
+	userProfile: UserProfile;
+
+	/**
+	 * Options to be passed to the API.
+	 */
+	options?: ServiceOptions;
+};
+
+/**
+ * Input type for `configureAutoTrack`.
+ */
+export type AnalyticsConfigureAutoTrackInput = {
+	enable: boolean;
+} & (
+	| {
+			type: 'session';
+			options?: SessionTrackingOptions;
+	  }
+	| {
+			type: 'pageView';
+			options?: PageViewTrackingOptions;
+	  }
+	| {
+			type: 'event';
+			options?: EventTrackingOptions;
+	  }
+);

package/src/types/kinesis.ts

@@ -0,0 +1,13 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export type KinesisStream = {
+	region: string;
+	streamName: string;
+};
+
+export type KinesisShard = KinesisStream & {
+	partitionKey: string;
+};
+
+export type KinesisEventData = Record<string, unknown> | Uint8Array;

package/src/types/options.ts

@@ -0,0 +1,7 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Base type for service options.
+ */
+export type AnalyticsServiceOptions = Record<string, unknown>;

package/src/types/trackers.ts

@@ -0,0 +1,35 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export type SessionTrackingOptions = {
+	attributes?: TrackerAttributes;
+};
+
+export type PageViewTrackingOptions = {
+	attributes?: TrackerAttributes;
+	eventName?: string;
+	urlProvider?: () => string;
+	appType?: 'multiPage' | 'singlePage';
+};
+
+export type EventTrackingOptions = {
+	attributes?: TrackerAttributes;
+	events?: DOMEvent[];
+	selectorPrefix?: string;
+};
+
+export type TrackerType = 'event' | 'pageView' | 'session';
+
+export type TrackerAttributes = Record<string, string>;
+
+export type TrackerEventRecorder = (
+	eventName: string,
+	attributes: TrackerAttributes
+) => void;
+
+export type DOMEvent = keyof GlobalEventHandlersEventMap;
+
+export interface TrackerInterface {
+	configure(eventRecorder: TrackerEventRecorder, options?: object): void;
+	cleanup(): void;
+}

package/src/utils/eventBuffer/EventBuffer.ts

@@ -0,0 +1,84 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { ConsoleLogger } from '@aws-amplify/core';
+import { EventBufferConfig, IAnalyticsClient } from './';
+
+const logger = new ConsoleLogger('EventBuffer');
+
+export class EventBuffer<T> {
+	private list: T[];
+	private readonly config: EventBufferConfig;
+	private getAnalyticsClient: () => IAnalyticsClient<T>;
+
+	private timer?: ReturnType<typeof setInterval>;
+
+	constructor(
+		config: EventBufferConfig,
+		getAnalyticsClient: () => IAnalyticsClient<T>
+	) {
+		this.list = [];
+		this.config = config;
+		this.getAnalyticsClient = getAnalyticsClient;
+		this.startEventLoop();
+	}
+
+	public append(...events: T[]) {
+		for (const event of events) {
+			if (this.list.length + 1 > this.config.bufferSize) {
+				logger.debug(
+					`Exceed ${typeof event} event buffer limits, event dropped`
+				);
+				continue;
+			}
+			this.list.push(event);
+		}
+	}
+
+	public flushAll(): Promise<void> {
+		return this.submitEvents(this.list.length);
+	}
+
+	public release() {
+		this.list = [];
+		if (this.timer) {
+			clearInterval(this.timer);
+		}
+	}
+
+	public get length() {
+		return this.list.length;
+	}
+
+	private head(count: number) {
+		return this.list.splice(0, count);
+	}
+
+	private insertAtBeginning(...data: T[]) {
+		this.list.unshift(...data);
+	}
+
+	private startEventLoop() {
+		if (this.timer) {
+			clearInterval(this.timer);
+		}
+
+		const { flushSize, flushInterval } = this.config;
+		setInterval(() => {
+			this.submitEvents(flushSize);
+		}, flushInterval);
+	}
+
+	private submitEvents(count: number): Promise<void> {
+		const events = this.head(count);
+		if (events.length === 0) {
+			return Promise.resolve();
+		}
+
+		return this.getAnalyticsClient()(events).then(result => {
+			if (result.length > 0) {
+				this.insertAtBeginning(...result);
+			}
+		});
+	}
+}

package/src/utils/eventBuffer/index.ts

@@ -0,0 +1,5 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { EventBuffer } from './EventBuffer';
+export { EventBufferConfig, IAnalyticsClient } from './types';

package/src/utils/eventBuffer/types.ts

@@ -0,0 +1,12 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export interface IAnalyticsClient<T> {
+	(events: T[]): Promise<T[]>;
+}
+
+export type EventBufferConfig = {
+	flushSize: number;
+	flushInterval: number;
+	bufferSize: number;
+};

package/src/utils/groupBy.ts

@@ -0,0 +1,12 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export const groupBy = <T>(
+	getGroupId: (x: T) => string,
+	list: T[]
+): Record<string, T[]> => {
+	return list.reduce((result, current) => {
+		const groupId = getGroupId(current);
+		return { ...result, [groupId]: [...(result[groupId] ?? []), current] };
+	}, {} as Record<string, T[]>);
+};

package/src/utils/index.ts

@@ -0,0 +1,21 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { resolveCredentials } from './resolveCredentials';
+export { groupBy } from './groupBy';
+export {
+	EventBuffer,
+	IAnalyticsClient,
+	EventBufferConfig,
+} from './eventBuffer';
+export {
+	enableAnalytics,
+	disableAnalytics,
+	isAnalyticsEnabled,
+} from './statusHelpers';
+export {
+	getAnalyticsUserAgent,
+	getAnalyticsUserAgentString,
+} from './userAgent';
+export { updateProviderTrackers } from './trackerHelpers';
+export { validateTrackerConfiguration } from './trackerConfigHelpers';

package/src/utils/resolveCredentials.ts

@@ -0,0 +1,14 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AnalyticsValidationErrorCode, assertValidationError } from '../errors';
+import { fetchAuthSession } from '@aws-amplify/core';
+
+export const resolveCredentials = async () => {
+	const { credentials, identityId } = await fetchAuthSession();
+	assertValidationError(
+		!!credentials,
+		AnalyticsValidationErrorCode.NoCredentials
+	);
+	return { credentials, identityId };
+};

package/src/utils/statusHelpers.ts

@@ -0,0 +1,17 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+let analyticsEnabled = true;
+
+export const enableAnalytics = () => {
+	analyticsEnabled = true;
+};
+
+export const disableAnalytics = () => {
+	analyticsEnabled = false;
+};
+
+/**
+ * Returns the current status of the Analytics category.
+ */
+export const isAnalyticsEnabled = () => analyticsEnabled;

package/src/utils/trackerConfigHelpers.native.ts

@@ -0,0 +1,18 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AnalyticsValidationErrorCode, assertValidationError } from '../errors';
+import { AnalyticsConfigureAutoTrackInput } from '../types';
+
+/**
+ * Validates tracker configuration.
+ */
+export const validateTrackerConfiguration = (
+	input: AnalyticsConfigureAutoTrackInput
+) => {
+	// React Native only supports session tracking
+	assertValidationError(
+		input.type === 'session',
+		AnalyticsValidationErrorCode.UnsupportedPlatform
+	);
+};

package/src/utils/trackerConfigHelpers.ts

@@ -0,0 +1,19 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AnalyticsValidationErrorCode, assertValidationError } from '../errors';
+import { AnalyticsConfigureAutoTrackInput } from '../types';
+
+/**
+ * Validates tracker configuration.
+ */
+export const validateTrackerConfiguration = (
+	input: AnalyticsConfigureAutoTrackInput
+) => {
+	assertValidationError(
+		input.type === 'event' ||
+			input.type === 'pageView' ||
+			input.type === 'session',
+		AnalyticsValidationErrorCode.InvalidTracker
+	);
+};

package/src/utils/trackerHelpers.ts

@@ -0,0 +1,57 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	TrackerAttributes,
+	TrackerEventRecorder,
+	TrackerInterface,
+	TrackerType,
+} from '../types/trackers';
+import { EventTracker, PageViewTracker, SessionTracker } from '../trackers';
+import { ConfigureAutoTrackInput } from '../providers/pinpoint';
+
+/**
+ * Updates a provider's trackers as appropriate for the provided auto-track configuration.
+ *
+ * @remark
+ * This utility will mutate the provider's configured trackers via `providerTrackers`.
+ */
+export const updateProviderTrackers = (
+	input: ConfigureAutoTrackInput,
+	providerEventRecorder: TrackerEventRecorder,
+	providerTrackers: Partial<Record<TrackerType, TrackerInterface>>
+) => {
+	let trackerInstance;
+	const trackerType = input.type;
+	const currentTracker = providerTrackers[trackerType];
+
+	// Check if the tracker was disabled & should be cleaned up
+	if (!input.enable) {
+		if (currentTracker) {
+			currentTracker.cleanup();
+			delete providerTrackers[trackerType];
+		}
+
+		return;
+	}
+
+	// Re-configure the existing tracker, or create & configure an instance if it doesn't exist yet
+	if (currentTracker) {
+		currentTracker.configure(providerEventRecorder, input.options);
+
+		return;
+	}
+
+	// Create a new tracker instance for the type
+	if (trackerType === 'event') {
+		trackerInstance = new EventTracker(providerEventRecorder, input.options);
+	} else if (trackerType === 'pageView') {
+		trackerInstance = new PageViewTracker(providerEventRecorder, input.options);
+	} else if (trackerType === 'session') {
+		trackerInstance = new SessionTracker(providerEventRecorder, input.options);
+	}
+
+	if (trackerInstance) {
+		providerTrackers[trackerType] = trackerInstance;
+	}
+};

package/lib/providers/pinpoint/types/errors.d.ts

@@ -1,9 +0,0 @@
-export declare enum UpdateEndpointException {
-    BadRequestException = "BadRequestException",
-    ForbiddenException = "ForbiddenException",
-    InternalServerErrorException = "InternalServerErrorException",
-    MethodNotAllowedException = "MethodNotAllowedException",
-    NotFoundException = "NotFoundException",
-    PayloadTooLargeException = "PayloadTooLargeException",
-    TooManyRequestsException = "TooManyRequestsException"
-}

package/lib/providers/pinpoint/types/errors.js

@@ -1,15 +0,0 @@
-"use strict";
-// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-// SPDX-License-Identifier: Apache-2.0
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.UpdateEndpointException = void 0;
-var UpdateEndpointException;
-(function (UpdateEndpointException) {
-    UpdateEndpointException["BadRequestException"] = "BadRequestException";
-    UpdateEndpointException["ForbiddenException"] = "ForbiddenException";
-    UpdateEndpointException["InternalServerErrorException"] = "InternalServerErrorException";
-    UpdateEndpointException["MethodNotAllowedException"] = "MethodNotAllowedException";
-    UpdateEndpointException["NotFoundException"] = "NotFoundException";
-    UpdateEndpointException["PayloadTooLargeException"] = "PayloadTooLargeException";
-    UpdateEndpointException["TooManyRequestsException"] = "TooManyRequestsException";
-})(UpdateEndpointException = exports.UpdateEndpointException || (exports.UpdateEndpointException = {}));