cdk-amazon-connect-constructs 0.1.0-alpha.0

package/src/connect-instance.ts

@@ -0,0 +1,190 @@
+import { aws_connect as connect } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { resourceNameFromSlashArn } from './private/arn';
+
+/**
+ * Common identity-management modes supported by Amazon Connect.
+ */
+export enum IdentityManagementType {
+  /**
+   * Amazon Connect stores user identities.
+   */
+  CONNECT_MANAGED = 'CONNECT_MANAGED',
+
+  /**
+   * Users are managed by an existing SAML identity provider.
+   */
+  SAML = 'SAML',
+
+  /**
+   * Users are managed by AWS Directory Service.
+   */
+  EXISTING_DIRECTORY = 'EXISTING_DIRECTORY',
+}
+
+/**
+ * Capabilities enabled for an Amazon Connect instance.
+ */
+export interface ConnectInstanceAttributes {
+  /**
+   * Allow inbound calls.
+   *
+   * @default true
+   */
+  readonly inboundCalls?: boolean;
+
+  /**
+   * Allow outbound calls.
+   *
+   * @default true
+   */
+  readonly outboundCalls?: boolean;
+
+  /**
+   * Enable contact flow logs.
+   *
+   * @default false
+   */
+  readonly contactflowLogs?: boolean;
+
+  /**
+   * Enable contact lens.
+   *
+   * @default false
+   */
+  readonly contactLens?: boolean;
+
+  /**
+   * Enable early media.
+   *
+   * @default false
+   */
+  readonly earlyMedia?: boolean;
+
+  /**
+   * Enable use of custom chatbots.
+   *
+   * @default false
+   */
+  readonly useCustomTtsVoices?: boolean;
+}
+
+/**
+ * An Amazon Connect instance reference.
+ */
+export interface IConnectInstance {
+  /**
+   * The Amazon Connect instance ARN.
+   */
+  readonly instanceArn: string;
+
+  /**
+   * The Amazon Connect instance ID.
+   */
+  readonly instanceId: string;
+}
+
+/**
+ * Properties for a new Amazon Connect instance.
+ */
+export interface ConnectInstanceProps {
+  /**
+   * The instance alias shown in the Amazon Connect console.
+   */
+  readonly instanceAlias: string;
+
+  /**
+   * How identities are managed for this instance.
+   *
+   * @default IdentityManagementType.CONNECT_MANAGED
+   */
+  readonly identityManagementType?: IdentityManagementType;
+
+  /**
+   * Existing AWS Directory Service directory ID.
+   *
+   * Required when identityManagementType is EXISTING_DIRECTORY.
+   *
+   * @default - no directory ID
+   */
+  readonly directoryId?: string;
+
+  /**
+   * Instance capabilities.
+   *
+   * @default - inbound and outbound calls enabled
+   */
+  readonly attributes?: ConnectInstanceAttributes;
+}
+
+/**
+ * L2-style wrapper for AWS::Connect::Instance.
+ */
+export class ConnectInstance extends Construct implements IConnectInstance {
+  /**
+   * Import an existing Amazon Connect instance by ARN.
+   */
+  public static fromInstanceArn(scope: Construct, id: string, instanceArn: string): IConnectInstance {
+    return new ImportedConnectInstance(scope, id, instanceArn);
+  }
+
+  /**
+   * The underlying CloudFormation resource.
+   */
+  public readonly resource: connect.CfnInstance;
+
+  /**
+   * The Amazon Connect instance ARN.
+   */
+  public readonly instanceArn: string;
+
+  /**
+   * The Amazon Connect instance ID.
+   */
+  public readonly instanceId: string;
+
+  public constructor(scope: Construct, id: string, props: ConnectInstanceProps) {
+    super(scope, id);
+
+    if (!props.instanceAlias.trim()) {
+      throw new Error('instanceAlias must not be empty.');
+    }
+
+    const identityManagementType = props.identityManagementType ?? IdentityManagementType.CONNECT_MANAGED;
+    if (identityManagementType === IdentityManagementType.EXISTING_DIRECTORY && !props.directoryId) {
+      throw new Error('directoryId is required when identityManagementType is EXISTING_DIRECTORY.');
+    }
+
+    this.resource = new connect.CfnInstance(this, 'Resource', {
+      attributes: toCfnAttributes(props.attributes),
+      directoryId: props.directoryId,
+      identityManagementType,
+      instanceAlias: props.instanceAlias,
+    });
+
+    this.instanceArn = this.resource.getAtt('Arn').toString();
+    this.instanceId = this.resource.getAtt('Id').toString();
+  }
+}
+
+class ImportedConnectInstance extends Construct implements IConnectInstance {
+  public readonly instanceArn: string;
+  public readonly instanceId: string;
+
+  public constructor(scope: Construct, id: string, instanceArn: string) {
+    super(scope, id);
+    this.instanceArn = instanceArn;
+    this.instanceId = resourceNameFromSlashArn(this, instanceArn);
+  }
+}
+
+function toCfnAttributes(attributes?: ConnectInstanceAttributes): connect.CfnInstance.AttributesProperty {
+  return {
+    inboundCalls: attributes?.inboundCalls ?? true,
+    outboundCalls: attributes?.outboundCalls ?? true,
+    contactflowLogs: attributes?.contactflowLogs ?? false,
+    contactLens: attributes?.contactLens ?? false,
+    earlyMedia: attributes?.earlyMedia ?? false,
+    useCustomTtsVoices: attributes?.useCustomTtsVoices ?? false,
+  };
+}

package/src/contact-flow.ts

@@ -0,0 +1,123 @@
+import { aws_connect as connect } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { IConnectInstance } from './connect-instance';
+
+/**
+ * Amazon Connect contact flow type.
+ */
+export enum ContactFlowType {
+  CONTACT_FLOW = 'CONTACT_FLOW',
+  CUSTOMER_QUEUE = 'CUSTOMER_QUEUE',
+  CUSTOMER_HOLD = 'CUSTOMER_HOLD',
+  CUSTOMER_WHISPER = 'CUSTOMER_WHISPER',
+  AGENT_HOLD = 'AGENT_HOLD',
+  AGENT_WHISPER = 'AGENT_WHISPER',
+  OUTBOUND_WHISPER = 'OUTBOUND_WHISPER',
+  AGENT_TRANSFER = 'AGENT_TRANSFER',
+  QUEUE_TRANSFER = 'QUEUE_TRANSFER',
+  CAMPAIGN = 'CAMPAIGN',
+}
+
+/**
+ * Contact flow lifecycle state.
+ */
+export enum ContactFlowState {
+  ACTIVE = 'ACTIVE',
+  ARCHIVED = 'ARCHIVED',
+}
+
+/**
+ * Properties for a JSON-backed contact flow.
+ */
+export interface ContactFlowProps {
+  /**
+   * The Amazon Connect instance that owns this contact flow.
+   */
+  readonly instance: IConnectInstance;
+
+  /**
+   * Contact flow name.
+   */
+  readonly name: string;
+
+  /**
+   * Serialized Amazon Connect contact flow JSON.
+   */
+  readonly content: string;
+
+  /**
+   * Contact flow type.
+   *
+   * @default ContactFlowType.CONTACT_FLOW
+   */
+  readonly contactFlowType?: ContactFlowType;
+
+  /**
+   * Optional description.
+   *
+   * @default - no description
+   */
+  readonly description?: string;
+
+  /**
+   * Flow state.
+   *
+   * @default ContactFlowState.ACTIVE
+   */
+  readonly state?: ContactFlowState;
+}
+
+/**
+ * L2-style wrapper for AWS::Connect::ContactFlow.
+ */
+export class ContactFlow extends Construct {
+  /**
+   * Create a serialized contact flow body from an object.
+   */
+  public static stringify(definition: { [key: string]: unknown }): string {
+    return JSON.stringify(definition, undefined, 2);
+  }
+
+  /**
+   * The underlying CloudFormation resource.
+   */
+  public readonly resource: connect.CfnContactFlow;
+
+  /**
+   * The contact flow ARN.
+   */
+  public readonly contactFlowArn: string;
+
+  public constructor(scope: Construct, id: string, props: ContactFlowProps) {
+    super(scope, id);
+
+    if (!props.name.trim()) {
+      throw new Error('name must not be empty.');
+    }
+    validateJson(props.content);
+
+    this.resource = new connect.CfnContactFlow(this, 'Resource', {
+      content: props.content,
+      description: props.description,
+      instanceArn: props.instance.instanceArn,
+      name: props.name,
+      state: props.state ?? ContactFlowState.ACTIVE,
+      type: props.contactFlowType ?? ContactFlowType.CONTACT_FLOW,
+    });
+
+    this.contactFlowArn = this.resource.getAtt('ContactFlowArn').toString();
+  }
+}
+
+function validateJson(content: string): void {
+  if (!content.trim()) {
+    throw new Error('content must not be empty.');
+  }
+
+  try {
+    JSON.parse(content);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`content must be valid JSON: ${message}`);
+  }
+}

package/src/hours-of-operation.ts

@@ -0,0 +1,184 @@
+import { aws_connect as connect } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { IConnectInstance } from './connect-instance';
+import { resourceNameFromSlashArn } from './private/arn';
+
+/**
+ * Days supported by Amazon Connect hours of operation.
+ */
+export enum DayOfWeek {
+  SUNDAY = 'SUNDAY',
+  MONDAY = 'MONDAY',
+  TUESDAY = 'TUESDAY',
+  WEDNESDAY = 'WEDNESDAY',
+  THURSDAY = 'THURSDAY',
+  FRIDAY = 'FRIDAY',
+  SATURDAY = 'SATURDAY',
+}
+
+/**
+ * A time of day in 24-hour format.
+ */
+export interface TimeOfDay {
+  /**
+   * Hour in local time, from 0 through 23.
+   */
+  readonly hours: number;
+
+  /**
+   * Minute in local time, from 0 through 59.
+   *
+   * @default 0
+   */
+  readonly minutes?: number;
+}
+
+/**
+ * A weekly open interval for an Amazon Connect queue.
+ */
+export interface WeeklyTimeRange {
+  /**
+   * Day of week for this interval.
+   */
+  readonly day: DayOfWeek;
+
+  /**
+   * Interval start time.
+   */
+  readonly startTime: TimeOfDay;
+
+  /**
+   * Interval end time.
+   */
+  readonly endTime: TimeOfDay;
+}
+
+/**
+ * An Amazon Connect hours-of-operation reference.
+ */
+export interface IHoursOfOperation {
+  /**
+   * The hours of operation ARN.
+   */
+  readonly hoursOfOperationArn: string;
+}
+
+/**
+ * Properties for HoursOfOperation.
+ */
+export interface HoursOfOperationProps {
+  /**
+   * The Amazon Connect instance that owns these hours.
+   */
+  readonly instance: IConnectInstance;
+
+  /**
+   * Display name.
+   */
+  readonly name: string;
+
+  /**
+   * IANA time zone, for example America/New_York.
+   */
+  readonly timeZone: string;
+
+  /**
+   * Weekly open intervals.
+   */
+  readonly config: WeeklyTimeRange[];
+
+  /**
+   * Optional description.
+   *
+   * @default - no description
+   */
+  readonly description?: string;
+}
+
+/**
+ * L2-style wrapper for AWS::Connect::HoursOfOperation.
+ */
+export class HoursOfOperation extends Construct implements IHoursOfOperation {
+  /**
+   * Import existing hours of operation by ARN.
+   */
+  public static fromHoursOfOperationArn(
+    scope: Construct,
+    id: string,
+    hoursOfOperationArn: string,
+  ): IHoursOfOperation {
+    return new ImportedHoursOfOperation(scope, id, hoursOfOperationArn);
+  }
+
+  /**
+   * The underlying CloudFormation resource.
+   */
+  public readonly resource: connect.CfnHoursOfOperation;
+
+  /**
+   * The hours of operation ARN.
+   */
+  public readonly hoursOfOperationArn: string;
+
+  public constructor(scope: Construct, id: string, props: HoursOfOperationProps) {
+    super(scope, id);
+
+    if (!props.name.trim()) {
+      throw new Error('name must not be empty.');
+    }
+    if (!props.timeZone.trim()) {
+      throw new Error('timeZone must not be empty.');
+    }
+    if (props.config.length === 0) {
+      throw new Error('config must include at least one weekly time range.');
+    }
+
+    this.resource = new connect.CfnHoursOfOperation(this, 'Resource', {
+      config: props.config.map(toCfnRange),
+      description: props.description,
+      instanceArn: props.instance.instanceArn,
+      name: props.name,
+      timeZone: props.timeZone,
+    });
+
+    this.hoursOfOperationArn = this.resource.getAtt('HoursOfOperationArn').toString();
+  }
+}
+
+class ImportedHoursOfOperation extends Construct implements IHoursOfOperation {
+  public readonly hoursOfOperationArn: string;
+
+  public constructor(scope: Construct, id: string, hoursOfOperationArn: string) {
+    super(scope, id);
+    this.hoursOfOperationArn = hoursOfOperationArn;
+    resourceNameFromSlashArn(this, hoursOfOperationArn);
+  }
+}
+
+function toCfnRange(range: WeeklyTimeRange): connect.CfnHoursOfOperation.HoursOfOperationConfigProperty {
+  validateTime(range.startTime, 'startTime');
+  validateTime(range.endTime, 'endTime');
+
+  return {
+    day: range.day,
+    startTime: toCfnTime(range.startTime),
+    endTime: toCfnTime(range.endTime),
+  };
+}
+
+function toCfnTime(time: TimeOfDay): connect.CfnHoursOfOperation.HoursOfOperationTimeSliceProperty {
+  return {
+    hours: time.hours,
+    minutes: time.minutes ?? 0,
+  };
+}
+
+function validateTime(time: TimeOfDay, name: string): void {
+  if (time.hours < 0 || time.hours > 23 || !Number.isInteger(time.hours)) {
+    throw new Error(`${name}.hours must be an integer from 0 through 23.`);
+  }
+  const minutes = time.minutes ?? 0;
+  if (minutes < 0 || minutes > 59 || !Number.isInteger(minutes)) {
+    throw new Error(`${name}.minutes must be an integer from 0 through 59.`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './connect-instance';
+export * from './hours-of-operation';
+export * from './queue';
+export * from './routing-profile';
+export * from './contact-flow';
+export * from './lambda-integration';

package/src/lambda-integration.ts

@@ -0,0 +1,51 @@
+import { aws_connect as connect, aws_iam as iam, aws_lambda as lambda } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { IConnectInstance } from './connect-instance';
+
+/**
+ * Properties for LambdaIntegration.
+ */
+export interface LambdaIntegrationProps {
+  /**
+   * Amazon Connect instance to associate with the function.
+   */
+  readonly instance: IConnectInstance;
+
+  /**
+   * Lambda function that Amazon Connect can invoke.
+   */
+  readonly function: lambda.IFunction;
+}
+
+/**
+ * Associates a Lambda function with an Amazon Connect instance and grants invoke access.
+ */
+export class LambdaIntegration extends Construct {
+  /**
+   * The underlying AWS::Connect::IntegrationAssociation resource.
+   */
+  public readonly association: connect.CfnIntegrationAssociation;
+
+  public constructor(scope: Construct, id: string, props: LambdaIntegrationProps) {
+    super(scope, id);
+
+    if (!props.instance) {
+      throw new Error('instance is required.');
+    }
+    if (!props.function) {
+      throw new Error('function is required.');
+    }
+
+    this.association = new connect.CfnIntegrationAssociation(this, 'Resource', {
+      instanceId: props.instance.instanceId,
+      integrationArn: props.function.functionArn,
+      integrationType: 'LAMBDA_FUNCTION',
+    });
+
+    props.function.addPermission('AllowAmazonConnectInvoke', {
+      action: 'lambda:InvokeFunction',
+      principal: new iam.ServicePrincipal('connect.amazonaws.com'),
+      sourceArn: props.instance.instanceArn,
+    });
+  }
+}

package/src/private/arn.ts

@@ -0,0 +1,6 @@
+import { ArnFormat, Stack } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+
+export function resourceNameFromSlashArn(scope: Construct, arn: string): string {
+  return Stack.of(scope).splitArn(arn, ArnFormat.SLASH_RESOURCE_NAME).resourceName ?? arn;
+}

package/src/queue.ts

@@ -0,0 +1,152 @@
+import { aws_connect as connect } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { IConnectInstance } from './connect-instance';
+import { IHoursOfOperation } from './hours-of-operation';
+import { resourceNameFromSlashArn } from './private/arn';
+
+/**
+ * Queue availability.
+ */
+export enum QueueStatus {
+  ENABLED = 'ENABLED',
+  DISABLED = 'DISABLED',
+}
+
+/**
+ * A phone-number-like outbound caller identity.
+ */
+export interface OutboundCallerConfig {
+  /**
+   * Outbound caller ID name.
+   *
+   * @default - Amazon Connect default
+   */
+  readonly outboundCallerIdName?: string;
+
+  /**
+   * Outbound caller ID phone number ARN.
+   *
+   * @default - Amazon Connect default
+   */
+  readonly outboundCallerIdNumberArn?: string;
+
+  /**
+   * Outbound flow ARN.
+   *
+   * @default - Amazon Connect default
+   */
+  readonly outboundFlowArn?: string;
+}
+
+/**
+ * An Amazon Connect queue reference.
+ */
+export interface IQueue {
+  /**
+   * The queue ARN.
+   */
+  readonly queueArn: string;
+}
+
+/**
+ * Properties for Queue.
+ */
+export interface QueueProps {
+  /**
+   * The Amazon Connect instance that owns this queue.
+   */
+  readonly instance: IConnectInstance;
+
+  /**
+   * Queue name.
+   */
+  readonly name: string;
+
+  /**
+   * Hours of operation for this queue.
+   */
+  readonly hoursOfOperation: IHoursOfOperation;
+
+  /**
+   * Optional description.
+   *
+   * @default - no description
+   */
+  readonly description?: string;
+
+  /**
+   * Maximum contacts allowed in the queue.
+   *
+   * @default - Amazon Connect default
+   */
+  readonly maxContacts?: number;
+
+  /**
+   * Outbound caller configuration.
+   *
+   * @default - Amazon Connect default
+   */
+  readonly outboundCallerConfig?: OutboundCallerConfig;
+
+  /**
+   * Queue status.
+   *
+   * @default QueueStatus.ENABLED
+   */
+  readonly status?: QueueStatus;
+}
+
+/**
+ * L2-style wrapper for AWS::Connect::Queue.
+ */
+export class Queue extends Construct implements IQueue {
+  /**
+   * Import an existing Amazon Connect queue by ARN.
+   */
+  public static fromQueueArn(scope: Construct, id: string, queueArn: string): IQueue {
+    return new ImportedQueue(scope, id, queueArn);
+  }
+
+  /**
+   * The underlying CloudFormation resource.
+   */
+  public readonly resource: connect.CfnQueue;
+
+  /**
+   * The queue ARN.
+   */
+  public readonly queueArn: string;
+
+  public constructor(scope: Construct, id: string, props: QueueProps) {
+    super(scope, id);
+
+    if (!props.name.trim()) {
+      throw new Error('name must not be empty.');
+    }
+    if (props.maxContacts !== undefined && props.maxContacts < 0) {
+      throw new Error('maxContacts must be greater than or equal to 0.');
+    }
+
+    this.resource = new connect.CfnQueue(this, 'Resource', {
+      description: props.description,
+      hoursOfOperationArn: props.hoursOfOperation.hoursOfOperationArn,
+      instanceArn: props.instance.instanceArn,
+      maxContacts: props.maxContacts,
+      name: props.name,
+      outboundCallerConfig: props.outboundCallerConfig,
+      status: props.status ?? QueueStatus.ENABLED,
+    });
+
+    this.queueArn = this.resource.getAtt('QueueArn').toString();
+  }
+}
+
+class ImportedQueue extends Construct implements IQueue {
+  public readonly queueArn: string;
+
+  public constructor(scope: Construct, id: string, queueArn: string) {
+    super(scope, id);
+    this.queueArn = queueArn;
+    resourceNameFromSlashArn(this, queueArn);
+  }
+}