From 96e589ef43142661c537a4d0eb18efc196a9c29b Mon Sep 17 00:00:00 2001 From: Allan Zheng Date: Tue, 23 Jan 2024 12:26:56 -0800 Subject: [PATCH 1/2] docs(auth,analytics): adding in-line docs for public apis --- .../providers/kinesis-firehose/apis/record.ts | 17 +++++++++++++ .../src/providers/kinesis/apis/record.ts | 21 ++++++++++++++++ .../src/providers/personalize/apis/record.ts | 25 +++++++++++++++++++ .../src/providers/pinpoint/apis/record.ts | 2 +- .../cognito/tokenProvider/tokenProvider.ts | 5 ++++ packages/core/src/singleton/Auth/index.ts | 9 +++++++ 6 files changed, 78 insertions(+), 1 deletion(-) diff --git a/packages/analytics/src/providers/kinesis-firehose/apis/record.ts b/packages/analytics/src/providers/kinesis-firehose/apis/record.ts index 917dd95f66f..af7d0138299 100644 --- a/packages/analytics/src/providers/kinesis-firehose/apis/record.ts +++ b/packages/analytics/src/providers/kinesis-firehose/apis/record.ts @@ -14,6 +14,23 @@ import { ConsoleLogger } from '@aws-amplify/core'; 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.'); diff --git a/packages/analytics/src/providers/kinesis/apis/record.ts b/packages/analytics/src/providers/kinesis/apis/record.ts index dbfabab423e..dbdc5eee3fc 100644 --- a/packages/analytics/src/providers/kinesis/apis/record.ts +++ b/packages/analytics/src/providers/kinesis/apis/record.ts @@ -15,6 +15,27 @@ import { ConsoleLogger } from '@aws-amplify/core'; const logger = new ConsoleLogger('Kinesis'); +/** + * Record one analytic event and send it to Kinesis. Events will be buffered and periodically sent to + * Kinesis. + * + * @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: 'myKinesisStream', + * partitionKey: 'myPartitionKey', + * data: { } // The data blob to put into the record + * }); + * ``` + * @param input - The event to record. + * + * @returns void + */ export const record = ({ streamName, partitionKey, diff --git a/packages/analytics/src/providers/personalize/apis/record.ts b/packages/analytics/src/providers/personalize/apis/record.ts index 1ee479909a4..41b5345103e 100644 --- a/packages/analytics/src/providers/personalize/apis/record.ts +++ b/packages/analytics/src/providers/personalize/apis/record.ts @@ -23,6 +23,31 @@ import { const logger = new ConsoleLogger('Personalize'); +/** + * Record one analytic event and send it to Personalize. Events will be buffered and periodically sent to Amazon + * Personalize. + * + * For more examples, you can refer to {@link https://docs.amplify.aws/javascript/build-a-backend/more-features/analytics/personalize-recommendations/#working-with-the-api the API usage guidance.} + * + * @param input 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 an `Identify` event to Personalize. + * record({ + * eventType: "Identify", + * properties: { + * userId: "" + * } + * }); + * ``` + * @param input - The event to record. + * + * @returns void + */ export const record = ({ userId, eventId, diff --git a/packages/analytics/src/providers/pinpoint/apis/record.ts b/packages/analytics/src/providers/pinpoint/apis/record.ts index c9de36b02ee..e1a94f27ef0 100644 --- a/packages/analytics/src/providers/pinpoint/apis/record.ts +++ b/packages/analytics/src/providers/pinpoint/apis/record.ts @@ -23,7 +23,7 @@ const logger = new ConsoleLogger('Analytics'); /** * Records an Analytic event to Pinpoint. Events will be buffered and periodically sent to Pinpoint. * - * @param {RecordInput} params The input object used to construct the request. + * @param params The input object used to construct the request. * * @throws validation: {@link AnalyticsValidationErrorCode} - Thrown when the provided parameters or library * configuration is incorrect. diff --git a/packages/auth/src/providers/cognito/tokenProvider/tokenProvider.ts b/packages/auth/src/providers/cognito/tokenProvider/tokenProvider.ts index 7e5135395f4..107120988e7 100644 --- a/packages/auth/src/providers/cognito/tokenProvider/tokenProvider.ts +++ b/packages/auth/src/providers/cognito/tokenProvider/tokenProvider.ts @@ -3,6 +3,11 @@ import { CognitoUserPoolsTokenProvider } from './CognitoUserPoolsTokenProvider'; +/** + * The default provider for the JWT access token and ID token issued from the configured Cognito user pool. It manages + * the refresh and storage of the tokens. It stores the tokens in `window.localStorage` if available, and falls back to + * in-memory storage if not. + */ export const cognitoUserPoolsTokenProvider = new CognitoUserPoolsTokenProvider(); diff --git a/packages/core/src/singleton/Auth/index.ts b/packages/core/src/singleton/Auth/index.ts index d43f508674c..7a8ba9bdb01 100644 --- a/packages/core/src/singleton/Auth/index.ts +++ b/packages/core/src/singleton/Auth/index.ts @@ -44,6 +44,15 @@ export class AuthClass { this.authOptions = authOptions; } + /** + * Fetch the auth tokens, and the temporary AWS credentials and identity if they are configured. By default it + * does not refresh the auth tokens or credentials if they are loaded in storage already. You can force a refresh + * with `{ forceRefresh: true }` input. + * + * @param options - Options configuring the fetch behavior. + * + * @returns Promise of current auth session {@link AuthSession}. + */ async fetchAuthSession( options: FetchAuthSessionOptions = {} ): Promise { From ddb3971118cc9289d96d712121a1fb4417541575 Mon Sep 17 00:00:00 2001 From: Allan Zheng Date: Wed, 24 Jan 2024 09:18:59 -0800 Subject: [PATCH 2/2] fix: unblock the max length lint --- packages/analytics/tslint.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/analytics/tslint.json b/packages/analytics/tslint.json index 1bb9e144d24..5ff1ce61219 100644 --- a/packages/analytics/tslint.json +++ b/packages/analytics/tslint.json @@ -5,7 +5,7 @@ "jsRules": {}, "rules": { "prefer-const": true, - "max-line-length": [true, 120], + "max-line-length": [true, { "limit": 120, "ignore-pattern": "\\s\\*" }], "no-empty-interface": true, "no-var-keyword": true, "object-literal-shorthand": true,