@aws-amplify/analytics 0.0.0-unstable-1ca644b-20260128091132

package/src/providers/kinesis/types/buffer.ts

@@ -0,0 +1,21 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AWSCredentials } from '@aws-amplify/core/internals/utils';
+
+import { EventBufferConfig } from '../../../utils';
+import { KinesisShard } from '../../../types';
+
+export type KinesisBufferEvent = KinesisShard & {
+	event: Uint8Array;
+	timestamp: number;
+	retryCount: number;
+};
+
+export type KinesisEventBufferConfig = EventBufferConfig & {
+	region: string;
+	credentials: AWSCredentials;
+	identityId?: string;
+	resendLimit?: number;
+	userAgentValue?: string;
+};

package/src/providers/kinesis/types/index.ts

@@ -0,0 +1,5 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { RecordInput } from './inputs';
+export { KinesisBufferEvent, KinesisEventBufferConfig } from './buffer';

package/src/providers/kinesis/types/inputs.ts

@@ -0,0 +1,10 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { KinesisEventData } from '../../../types';
+
+export interface RecordInput {
+	streamName: string;
+	partitionKey: string;
+	data: KinesisEventData;
+}

package/src/providers/kinesis/utils/constants.ts

@@ -0,0 +1,9 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export const DEFAULT_KINESIS_CONFIG = {
+	bufferSize: 1_000,
+	flushSize: 100,
+	flushInterval: 5_000,
+	resendLimit: 5,
+};

package/src/providers/kinesis/utils/getEventBuffer.ts

@@ -0,0 +1,130 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	AWSCredentials,
+	haveCredentialsChanged,
+} from '@aws-amplify/core/internals/utils';
+import { KinesisClient, PutRecordsCommand } from '@aws-sdk/client-kinesis';
+
+import { KinesisBufferEvent, KinesisEventBufferConfig } from '../types';
+import { EventBuffer, IAnalyticsClient, groupBy } from '../../../utils';
+
+/**
+ * These Records hold cached event buffers and AWS clients.
+ * The hash key is determined by the region and session,
+ * consisting of a combined value comprising [region, sessionToken, identityId].
+ *
+ * Only one active session should exist at any given moment.
+ * When a new session is initiated, the previous ones should be released.
+ * */
+const eventBufferMap: Record<string, EventBuffer<KinesisBufferEvent>> = {};
+const cachedClients: Record<string, [KinesisClient, AWSCredentials]> = {};
+
+const createKinesisPutRecordsCommand = (
+	streamName: string,
+	events: KinesisBufferEvent[],
+): PutRecordsCommand =>
+	new PutRecordsCommand({
+		StreamName: streamName,
+		Records: events.map(event => ({
+			PartitionKey: event.partitionKey,
+			Data: event.event,
+		})),
+	});
+
+const submitEvents = async (
+	events: KinesisBufferEvent[],
+	client: KinesisClient,
+	resendLimit?: number,
+): Promise<KinesisBufferEvent[]> => {
+	const groupedByStreamName = Object.entries(
+		groupBy(event => event.streamName, events),
+	);
+	const requests = groupedByStreamName
+		.map(([streamName, groupedEvents]) =>
+			createKinesisPutRecordsCommand(streamName, groupedEvents),
+		)
+		.map(command => client.send(command));
+
+	const responses = await Promise.allSettled(requests);
+	const failedEvents = responses
+		.map((response, i) =>
+			response.status === 'rejected' ? groupedByStreamName[i][1] : [],
+		)
+		.flat();
+
+	return resendLimit
+		? failedEvents
+				.filter(event => event.retryCount < resendLimit)
+				.map(event => ({ ...event, retryCount: event.retryCount + 1 }))
+				.sort((a, b) => a.timestamp - b.timestamp)
+		: [];
+};
+
+export const getEventBuffer = ({
+	region,
+	flushInterval,
+	flushSize,
+	bufferSize,
+	credentials,
+	identityId,
+	resendLimit,
+	userAgentValue,
+}: KinesisEventBufferConfig): EventBuffer<KinesisBufferEvent> => {
+	const sessionIdentityKey = [region, identityId].filter(x => !!x).join('-');
+	const [cachedClient, cachedCredentials] =
+		cachedClients[sessionIdentityKey] ?? [];
+	let credentialsHaveChanged = false;
+
+	// Check if credentials have changed for the cached client
+	if (cachedClient) {
+		credentialsHaveChanged = haveCredentialsChanged(
+			cachedCredentials,
+			credentials,
+		);
+	}
+
+	if (!eventBufferMap[sessionIdentityKey] || credentialsHaveChanged) {
+		const getKinesisClient = (): IAnalyticsClient<KinesisBufferEvent> => {
+			if (!cachedClient || credentialsHaveChanged) {
+				cachedClients[sessionIdentityKey] = [
+					new KinesisClient({
+						credentials,
+						region,
+						customUserAgent: userAgentValue,
+					}),
+					credentials,
+				];
+			}
+
+			const [kinesisClient] = cachedClients[sessionIdentityKey];
+
+			return events => submitEvents(events, kinesisClient, resendLimit);
+		};
+
+		// create new session
+		eventBufferMap[sessionIdentityKey] = new EventBuffer<KinesisBufferEvent>(
+			{
+				flushInterval,
+				flushSize,
+				bufferSize,
+			},
+			getKinesisClient,
+		);
+
+		// release other sessions
+		const releaseSessionKeys = Object.keys(eventBufferMap).filter(
+			x => x !== sessionIdentityKey,
+		);
+		for (const releaseSessionKey of releaseSessionKeys) {
+			eventBufferMap[releaseSessionKey].flushAll().finally(() => {
+				eventBufferMap[releaseSessionKey].release();
+				delete eventBufferMap[releaseSessionKey];
+				delete cachedClients[releaseSessionKey];
+			});
+		}
+	}
+
+	return eventBufferMap[sessionIdentityKey];
+};

package/src/providers/kinesis/utils/resolveConfig.ts

@@ -0,0 +1,39 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Amplify } from '@aws-amplify/core';
+
+import {
+	AnalyticsValidationErrorCode,
+	assertValidationError,
+} from '../../../errors';
+
+import { DEFAULT_KINESIS_CONFIG } from './constants';
+
+export const resolveConfig = () => {
+	const config = Amplify.getConfig().Analytics?.Kinesis;
+	const {
+		region,
+		bufferSize = DEFAULT_KINESIS_CONFIG.bufferSize,
+		flushSize = DEFAULT_KINESIS_CONFIG.flushSize,
+		flushInterval = DEFAULT_KINESIS_CONFIG.flushInterval,
+		resendLimit,
+	} = {
+		...DEFAULT_KINESIS_CONFIG,
+		...config,
+	};
+
+	assertValidationError(!!region, AnalyticsValidationErrorCode.NoRegion);
+	assertValidationError(
+		flushSize < bufferSize,
+		AnalyticsValidationErrorCode.InvalidFlushSize,
+	);
+
+	return {
+		region,
+		bufferSize,
+		flushSize,
+		flushInterval,
+		resendLimit,
+	};
+};

package/src/providers/kinesis-firehose/apis/flushEvents.ts

@@ -0,0 +1,42 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AnalyticsAction } from '@aws-amplify/core/internals/utils';
+import { ConsoleLogger } from '@aws-amplify/core';
+
+import { getEventBuffer, resolveConfig } from '../utils';
+import {
+	getAnalyticsUserAgentString,
+	resolveCredentials,
+} from '../../../utils';
+
+const logger = new ConsoleLogger('KinesisFirehose');
+
+/**
+ * Flushes all buffered Kinesis events to the service.
+ *
+ * @note
+ * This API will make a best-effort attempt to flush events from the buffer. Events recorded immediately after invoking
+ * this API may not be included in the flush.
+ */
+export const flushEvents = () => {
+	const { region, flushSize, flushInterval, bufferSize, resendLimit } =
+		resolveConfig();
+	resolveCredentials()
+		.then(({ credentials, identityId }) =>
+			getEventBuffer({
+				region,
+				flushSize,
+				flushInterval,
+				bufferSize,
+				credentials,
+				identityId,
+				resendLimit,
+				userAgentValue: getAnalyticsUserAgentString(AnalyticsAction.Record),
+			}),
+		)
+		.then(eventBuffer => eventBuffer.flushAll())
+		.catch(e => {
+			logger.warn('Failed to flush events.', e);
+		});
+};

package/src/providers/kinesis-firehose/apis/index.ts

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

package/src/providers/kinesis-firehose/apis/record.ts

@@ -0,0 +1,71 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { fromUtf8 } from '@smithy/util-utf8';
+import { AnalyticsAction } from '@aws-amplify/core/internals/utils';
+import { ConsoleLogger } from '@aws-amplify/core';
+
+import { RecordInput } from '../types';
+import { getEventBuffer, resolveConfig } from '../utils';
+import {
+	getAnalyticsUserAgentString,
+	isAnalyticsEnabled,
+	resolveCredentials,
+} from '../../../utils';
+import { AnalyticsValidationErrorCode } from '../../../errors';
+
+const logger = new ConsoleLogger('KinesisFirehose');
+
+/**
+ * Record one analytic event and send it to Kinesis Data Firehose. Events will be buffered and periodically sent to
+ * Kinesis Data Firehose.
+ *
+ * @param params The input object used to construct the request.
+ *
+ * @throws validation: {@link AnalyticsValidationErrorCode} - Thrown when the provided parameters or library
+ *  configuration is incorrect.
+ *
+ * @example
+ * ```ts
+ * record({
+ *     streamName: 'myFirehoseStream',
+ *     data: { } // The data blob to put into the record
+ * });
+ * ```
+ */
+export const record = ({ streamName, data }: RecordInput): void => {
+	if (!isAnalyticsEnabled()) {
+		logger.debug('Analytics is disabled, event will not be recorded.');
+
+		return;
+	}
+
+	const timestamp = Date.now();
+	const { region, bufferSize, flushSize, flushInterval, resendLimit } =
+		resolveConfig();
+
+	resolveCredentials()
+		.then(({ credentials, identityId }) => {
+			const buffer = getEventBuffer({
+				region,
+				credentials,
+				identityId,
+				bufferSize,
+				flushSize,
+				flushInterval,
+				resendLimit,
+				userAgentValue: getAnalyticsUserAgentString(AnalyticsAction.Record),
+			});
+
+			buffer.append({
+				region,
+				streamName,
+				event: ArrayBuffer.isView(data) ? data : fromUtf8(JSON.stringify(data)),
+				timestamp,
+				retryCount: 0,
+			});
+		})
+		.catch(e => {
+			logger.warn('Failed to record event.', e);
+		});
+};

package/src/providers/kinesis-firehose/index.ts

@@ -0,0 +1,4 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { record, flushEvents } from './apis';

package/src/providers/kinesis-firehose/types/buffer.ts

@@ -0,0 +1,21 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AWSCredentials } from '@aws-amplify/core/internals/utils';
+
+import { EventBufferConfig } from '../../../utils';
+import { KinesisStream } from '../../../types';
+
+export type KinesisFirehoseBufferEvent = KinesisStream & {
+	event: Uint8Array;
+	retryCount: number;
+	timestamp: number;
+};
+
+export type KinesisFirehoseEventBufferConfig = EventBufferConfig & {
+	region: string;
+	credentials: AWSCredentials;
+	identityId?: string;
+	resendLimit?: number;
+	userAgentValue?: string;
+};

package/src/providers/kinesis-firehose/types/index.ts

@@ -0,0 +1,9 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { RecordInput } from './inputs';
+
+export {
+	KinesisFirehoseBufferEvent,
+	KinesisFirehoseEventBufferConfig,
+} from './buffer';

package/src/providers/kinesis-firehose/types/inputs.ts

@@ -0,0 +1,9 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { KinesisEventData } from '../../../types';
+
+export interface RecordInput {
+	streamName: string;
+	data: KinesisEventData;
+}

package/src/providers/kinesis-firehose/utils/constants.ts

@@ -0,0 +1,9 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export const DEFAULT_KINESIS_FIREHOSE_CONFIG = {
+	bufferSize: 1_000,
+	flushSize: 100,
+	flushInterval: 5_000,
+	resendLimit: 5,
+};

package/src/providers/kinesis-firehose/utils/getEventBuffer.ts

@@ -0,0 +1,138 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	AWSCredentials,
+	haveCredentialsChanged,
+} from '@aws-amplify/core/internals/utils';
+import {
+	FirehoseClient,
+	PutRecordBatchCommand,
+} from '@aws-sdk/client-firehose';
+
+import { EventBuffer, IAnalyticsClient, groupBy } from '../../../utils';
+import {
+	KinesisFirehoseBufferEvent,
+	KinesisFirehoseEventBufferConfig,
+} from '../types';
+
+/**
+ * These Records hold cached event buffers and AWS clients.
+ * The hash key is determined by the region and session,
+ * consisting of a combined value comprising [region, sessionToken, identityId].
+ *
+ * Only one active session should exist at any given moment.
+ * When a new session is initiated, the previous ones should be released.
+ * */
+const eventBufferMap: Record<
+	string,
+	EventBuffer<KinesisFirehoseBufferEvent>
+> = {};
+const cachedClients: Record<string, [FirehoseClient, AWSCredentials]> = {};
+
+const createPutRecordsBatchCommand = (
+	streamName: string,
+	events: KinesisFirehoseBufferEvent[],
+): PutRecordBatchCommand =>
+	new PutRecordBatchCommand({
+		DeliveryStreamName: streamName,
+		Records: events.map(event => ({
+			Data: event.event,
+		})),
+	});
+
+const submitEvents = async (
+	events: KinesisFirehoseBufferEvent[],
+	client: FirehoseClient,
+	resendLimit?: number,
+): Promise<KinesisFirehoseBufferEvent[]> => {
+	const groupedByStreamName = Object.entries(
+		groupBy(event => event.streamName, events),
+	);
+
+	const requests = groupedByStreamName
+		.map(([streamName, groupedEvents]) =>
+			createPutRecordsBatchCommand(streamName, groupedEvents),
+		)
+		.map(command => client.send(command));
+
+	const responses = await Promise.allSettled(requests);
+	const failedEvents = responses
+		.map((response, i) =>
+			response.status === 'rejected' ? groupedByStreamName[i][1] : [],
+		)
+		.flat();
+
+	return resendLimit
+		? failedEvents
+				.filter(event => event.retryCount < resendLimit)
+				.map(event => ({ ...event, retryCount: event.retryCount + 1 }))
+				.sort((a, b) => a.timestamp - b.timestamp)
+		: [];
+};
+
+export const getEventBuffer = ({
+	region,
+	credentials,
+	identityId,
+	bufferSize,
+	flushSize,
+	flushInterval,
+	resendLimit,
+	userAgentValue,
+}: KinesisFirehoseEventBufferConfig): EventBuffer<KinesisFirehoseBufferEvent> => {
+	const sessionIdentityKey = [region, identityId].filter(id => !!id).join('-');
+	const [cachedClient, cachedCredentials] =
+		cachedClients[sessionIdentityKey] ?? [];
+	let credentialsHaveChanged = false;
+
+	// Check if credentials have changed for the cached client
+	if (cachedClient) {
+		credentialsHaveChanged = haveCredentialsChanged(
+			cachedCredentials,
+			credentials,
+		);
+	}
+
+	if (!eventBufferMap[sessionIdentityKey] || credentialsHaveChanged) {
+		const getClient = (): IAnalyticsClient<KinesisFirehoseBufferEvent> => {
+			if (!cachedClient || credentialsHaveChanged) {
+				cachedClients[sessionIdentityKey] = [
+					new FirehoseClient({
+						region,
+						credentials,
+						customUserAgent: userAgentValue,
+					}),
+					credentials,
+				];
+			}
+
+			const [firehoseClient] = cachedClients[sessionIdentityKey];
+
+			return events => submitEvents(events, firehoseClient, resendLimit);
+		};
+
+		eventBufferMap[sessionIdentityKey] =
+			new EventBuffer<KinesisFirehoseBufferEvent>(
+				{
+					bufferSize,
+					flushSize,
+					flushInterval,
+				},
+				getClient,
+			);
+
+		const releaseSessionKeys = Object.keys(eventBufferMap).filter(
+			key => key !== sessionIdentityKey,
+		);
+		for (const releaseSessionKey of releaseSessionKeys) {
+			eventBufferMap[releaseSessionKey].flushAll().finally(() => {
+				eventBufferMap[releaseSessionKey].release();
+				delete eventBufferMap[releaseSessionKey];
+				delete cachedClients[releaseSessionKey];
+			});
+		}
+	}
+
+	return eventBufferMap[sessionIdentityKey];
+};

package/src/providers/kinesis-firehose/utils/index.ts

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

package/src/providers/kinesis-firehose/utils/resolveConfig.ts

@@ -0,0 +1,39 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Amplify } from '@aws-amplify/core';
+
+import {
+	AnalyticsValidationErrorCode,
+	assertValidationError,
+} from '../../../errors';
+
+import { DEFAULT_KINESIS_FIREHOSE_CONFIG } from './constants';
+
+export const resolveConfig = () => {
+	const config = Amplify.getConfig().Analytics?.KinesisFirehose;
+	const {
+		region,
+		bufferSize = DEFAULT_KINESIS_FIREHOSE_CONFIG.bufferSize,
+		flushSize = DEFAULT_KINESIS_FIREHOSE_CONFIG.flushSize,
+		flushInterval = DEFAULT_KINESIS_FIREHOSE_CONFIG.flushInterval,
+		resendLimit,
+	} = {
+		...DEFAULT_KINESIS_FIREHOSE_CONFIG,
+		...config,
+	};
+
+	assertValidationError(!!region, AnalyticsValidationErrorCode.NoRegion);
+	assertValidationError(
+		flushSize < bufferSize,
+		AnalyticsValidationErrorCode.InvalidFlushSize,
+	);
+
+	return {
+		region,
+		bufferSize,
+		flushSize,
+		flushInterval,
+		resendLimit,
+	};
+};

package/src/providers/personalize/apis/flushEvents.ts

@@ -0,0 +1,40 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AnalyticsAction } from '@aws-amplify/core/internals/utils';
+import { ConsoleLogger } from '@aws-amplify/core';
+
+import { getEventBuffer, resolveConfig } from '../utils';
+import {
+	getAnalyticsUserAgentString,
+	resolveCredentials,
+} from '../../../utils';
+
+const logger = new ConsoleLogger('Personalize');
+
+/**
+ * Flushes all buffered Personalize events to the service.
+ *
+ * @note
+ * This API will make a best-effort attempt to flush events from the buffer. Events recorded immediately after invoking
+ * this API may not be included in the flush.
+ */
+export const flushEvents = () => {
+	const { region, flushSize, bufferSize, flushInterval } = resolveConfig();
+	resolveCredentials()
+		.then(({ credentials, identityId }) =>
+			getEventBuffer({
+				region,
+				flushSize,
+				flushInterval,
+				bufferSize,
+				credentials,
+				identityId,
+				userAgentValue: getAnalyticsUserAgentString(AnalyticsAction.Record),
+			}),
+		)
+		.then(eventBuffer => eventBuffer.flushAll())
+		.catch(e => {
+			logger.warn('Failed to flush events', e);
+		});
+};

package/src/providers/personalize/apis/index.ts

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