feat(cognito): add analyticsConfiguration to UserPoolClient

packages/aws-cdk-lib/aws-cognito/README.md

@@ -1085,3 +1085,41 @@ userPool.addGroup('AnotherUserPoolGroup', {
   groupName: 'another-group-name'
 });
 ```
+
+### Analytics Configuration
+
+User pool clients can be configured with Amazon Pinpoint analytics to collect user activity metrics. This integration enables you to track user engagement and campaign effectiveness.
+
+📝 Note: Amazon Pinpoint isn't available in all AWS Regions. For a list of available Regions, see [Amazon Cognito and Amazon Pinpoint Region availability](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-pinpoint-integration.html#cognito-user-pools-find-region-mappings).
+
+The following example shows how to configure analytics for a user pool client:
+
+```ts
+const pool = new cognito.UserPool(this, 'Pool');
+
+new cognito.UserPoolClient(this, 'Client', {
+  userPool: pool,
+  analytics: {
+    // The ARN of your Pinpoint project
+    applicationArn: 'arn:aws:pinpoint:us-east-1:123456789012:app/abc123',
+
+    // Your Pinpoint project ID
+    applicationId: '123456789012',
+
+    // External ID for the IAM role
+    externalId: 'my-external-id',
+
+    // IAM role that Cognito can assume to publish to Pinpoint
+    roleArn: 'arn:aws:iam::123456789012:role/CognitoPinpointRole',
+
+    // Whether to include user data in analytics events
+    userDataShared: true,
+  },
+});
+```
+
+When configuring analytics:
+
+- `applicationArn` must be a valid ARN of a Pinpoint project
+- `roleArn` must be a valid IAM role ARN with permissions to publish to Pinpoint
+- Setting `userDataShared` to `true` allows Cognito to include user data in the analytics events

packages/aws-cdk-lib/aws-cognito/lib/user-pool-client.ts

@@ -353,6 +353,45 @@ export interface UserPoolClientProps extends UserPoolClientOptions {
    * The UserPool resource this client will have access to
    */
   readonly userPool: IUserPool;
+
+  /**
+   * The analytics configuration for this client.
+   */
+  readonly analytics?: AnalyticsConfiguration;
+}
+
+/**
+ * The settings for Amazon Pinpoint analytics configuration.
+ *
+ * With an analytics configuration, your application can collect user-activity metrics for user notifications with a Amazon Pinpoint campaign.
+ *
+ * Amazon Pinpoint isn't available in all AWS Regions. For a list of available Regions, see [Amazon Cognito and Amazon Pinpoint Region availability](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-pinpoint-integration.html#cognito-user-pools-find-region-mappings).
+ */
+export interface AnalyticsConfiguration {
+  /**
+   * The Amazon Resource Name (ARN) of an Amazon Pinpoint project that you want to connect to your user pool app client.
+   */
+  readonly applicationArn?: string;
+
+  /**
+   * Your Amazon Pinpoint project ID.
+   */
+  readonly applicationId?: string;
+
+  /**
+   * The [external ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) of the role that Amazon Cognito assumes to send analytics data to Amazon Pinpoint.
+   */
+  readonly externalId?: string;
+
+  /**
+   * The ARN of an AWS Identity and Access Management role that has the permissions required for Amazon Cognito to publish events to Amazon Pinpoint analytics.
+   */
+  readonly roleArn?: string;
+
+  /**
+   * If `UserDataShared` is `true` , Amazon Cognito includes user data in the events that it publishes to Amazon Pinpoint analytics.
+   */
+  readonly userDataShared?: boolean;
 }
 
 /**
@@ -447,6 +486,10 @@ export class UserPoolClient extends Resource implements IUserPoolClient {
       throw new Error('Cannot activate enablePropagateAdditionalUserContextData in an app client without a client secret.');
     }
 
+    if (props.analytics) {
+      this.validateAnalytics(props.analytics);
+    }
+
     this._generateSecret = props.generateSecret;
     this.userPool = props.userPool;
 
@@ -467,6 +510,7 @@ export class UserPoolClient extends Resource implements IUserPoolClient {
       writeAttributes: props.writeAttributes?.attributes(),
       enableTokenRevocation: props.enableTokenRevocation,
       enablePropagateAdditionalUserContextData: props.enablePropagateAdditionalUserContextData,
+      analyticsConfiguration: props.analytics,
     });
     this.configureAuthSessionValidity(resource, props);
     this.configureTokenValidity(resource, props);
@@ -618,4 +662,13 @@ export class UserPoolClient extends Resource implements IUserPoolClient {
       throw new Error(`${name}: Must be a duration between ${min.toHumanString()} and ${max.toHumanString()} (inclusive); received ${value.toHumanString()}.`);
     }
   }
+
+  private validateAnalytics(analytics: AnalyticsConfiguration) {
+    if (analytics.applicationArn && !Token.isUnresolved(analytics.applicationArn) && !analytics.applicationArn.startsWith('arn:')) {
+      throw new Error(`applicationArn must be start with "arn:"; received ${analytics.applicationArn}`);
+    }
+    if (analytics.roleArn && !Token.isUnresolved(analytics.roleArn) && !analytics.roleArn.startsWith('arn:')) {
+      throw new Error(`roleArn must be start with "arn:"; received ${analytics.roleArn}`);
+    }
+  }
 }

packages/aws-cdk-lib/aws-cognito/test/user-pool-client.test.ts

@@ -1342,4 +1342,70 @@ describe('User Pool Client', () => {
     ).toThrow(`defaultRedirectUri must match the \`^(?=.{1,1024}$)[\p{L}\p{M}\p{S}\p{N}\p{P}]+$\` pattern, got ${invalidUrl}`);
   });
 
+  test('should add analytics configuration to userPoolClients ', () => {
+    // GIVEN
+    const stack = new Stack();
+    const pool = new UserPool(stack, 'Pool');
+
+    // WHEN
+    new UserPoolClient(stack, 'Client', {
+      userPool: pool,
+      analytics: {
+        applicationArn: 'arn:aws:pinpoint:us-east-1:123456789012:application/abc123',
+        applicationId: '123456789012',
+        externalId: '123456789012',
+        roleArn: 'arn:aws:iam::123456789012:role/TestRole',
+        userDataShared: true,
+      },
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::Cognito::UserPoolClient', {
+      AnalyticsConfiguration: {
+        ApplicationArn: 'arn:aws:pinpoint:us-east-1:123456789012:application/abc123',
+        ApplicationId: '123456789012',
+        ExternalId: '123456789012',
+        RoleArn: 'arn:aws:iam::123456789012:role/TestRole',
+        UserDataShared: true,
+      },
+    });
+  });
+
+  test('throws an error when applicationArn is not an ARN', () => {
+    // GIVEN
+    const stack = new Stack();
+    const pool = new UserPool(stack, 'Pool');
+
+    // WHEN
+    // THEN
+    expect(() => new UserPoolClient(stack, 'Client', {
+      userPool: pool,
+      analytics: {
+        applicationArn: 'invalid-arn',
+        applicationId: '123456789012',
+        externalId: '123456789012',
+        roleArn: 'arn:aws:iam::123456789012:role/TestRole',
+        userDataShared: true,
+      },
+    })).toThrow('applicationArn must be start with "arn:"; received invalid-arn');
+  });
+
+  test('throws an error when roleArn is not an ARN', () => {
+    // GIVEN
+    const stack = new Stack();
+    const pool = new UserPool(stack, 'Pool');
+
+    // WHEN
+    // THEN
+    expect(() => new UserPoolClient(stack, 'Client', {
+      userPool: pool,
+      analytics: {
+        applicationArn: 'arn:aws:pinpoint:us-east-1:123456789012:application/abc123',
+        applicationId: '123456789012',
+        externalId: '123456789012',
+        roleArn: 'invalid-arn',
+        userDataShared: true,
+      },
+    })).toThrow('roleArn must be start with "arn:"; received invalid-arn');
+  });
 });