@aws-cdk/aws-bedrock-agentcore-alpha 2.221.0-alpha.0

package/agentcore/tools/browser.d.ts

@@ -0,0 +1,519 @@
+import { IResource, Resource } from 'aws-cdk-lib';
+import { DimensionsMap, Metric, MetricOptions } from 'aws-cdk-lib/aws-cloudwatch';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import { Location } from 'aws-cdk-lib/aws-s3';
+import { Construct } from 'constructs';
+import { BrowserNetworkConfiguration } from '../network/network-configuration';
+/******************************************************************************
+ *                                Interface
+ *****************************************************************************/
+/**
+ * Interface for Browser resources
+ */
+export interface IBrowserCustom extends IResource, iam.IGrantable, ec2.IConnectable {
+    /**
+     * The ARN of the browser resource
+     * @attribute
+     */
+    readonly browserArn: string;
+    /**
+     * The id of the browser
+     * @attribute
+     */
+    readonly browserId: string;
+    /**
+     * The IAM role that provides permissions for the browser to access AWS services
+     */
+    readonly executionRole: iam.IRole;
+    /**
+     * Timestamp when the browser was last updated
+     * @attribute
+     */
+    readonly lastUpdatedAt?: string;
+    /**
+     * The status of the browser
+     * @attribute
+     */
+    readonly status?: string;
+    /**
+     * Timestamp when the browser was created
+     * @attribute
+     */
+    readonly createdAt?: string;
+    /**
+     * Grants IAM actions to the IAM Principal
+     */
+    grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
+    /**
+     * Grants `Get` and `List` actions on the Browser
+     */
+    grantRead(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grants `Invoke`, `Start`, and `Update` actions on the Browser
+     */
+    grantUse(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Return the given named metric for this browser.
+     */
+    metric(metricName: string, dimensions: DimensionsMap, props?: MetricOptions): Metric;
+    /**
+     * Return the given named metric related to the API operation performed on this browser.
+     */
+    metricForApiOperation(metricName: string, operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric measuring the latency of a specific API operation performed on this browser.
+     */
+    metricLatencyForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric containing the total number of API requests made for a specific browser operation.
+     */
+    metricInvocationsForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric containing the number of errors for a specific API operation performed on this browser.
+     */
+    metricErrorsForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric containing the number of throttled requests for a specific API operation performed on this browser.
+     */
+    metricThrottlesForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric containing the number of system errors for a specific API operation performed on this browser.
+     */
+    metricSystemErrorsForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric containing the number of user errors for a specific API operation performed on this browser.
+     */
+    metricUserErrorsForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric measuring the duration of browser sessions.
+     */
+    metricSessionDuration(props?: MetricOptions): Metric;
+    /**
+     * Return a metric containing the number of user takeovers.
+     */
+    metricTakeOverCount(props?: MetricOptions): Metric;
+    /**
+     * Return a metric containing the number of user takeovers released.
+     */
+    metricTakeOverReleaseCount(props?: MetricOptions): Metric;
+    /**
+     * Return a metric measuring the duration of user takeovers.
+     */
+    metricTakeOverDuration(props?: MetricOptions): Metric;
+}
+/******************************************************************************
+ *                        ABSTRACT BASE CLASS
+ *****************************************************************************/
+/**
+ * Abstract base class for a Browser.
+ * Contains methods and attributes valid for Browsers either created with CDK or imported.
+ */
+export declare abstract class BrowserCustomBase extends Resource implements IBrowserCustom {
+    abstract readonly browserArn: string;
+    abstract readonly browserId: string;
+    abstract readonly lastUpdatedAt?: string;
+    abstract readonly status?: string;
+    abstract readonly createdAt?: string;
+    abstract readonly executionRole: iam.IRole;
+    /**
+     * The principal to grant permissions to
+     */
+    abstract readonly grantPrincipal: iam.IPrincipal;
+    /**
+     * An accessor for the Connections object that will fail if this Browser does not have a VPC
+     * configured.
+     */
+    get connections(): ec2.Connections;
+    /**
+     * The actual Connections object for this Browser. This may be unset in the event that a VPC has not
+     * been configured.
+     * @internal
+     */
+    protected _connections: ec2.Connections | undefined;
+    constructor(scope: Construct, id: string);
+    /**
+     * Grants IAM actions to the IAM Principal
+     * @param grantee - The IAM principal to grant permissions to
+     * @param actions - The actions to grant
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
+    /**
+     * Grant read permissions on this browser to an IAM principal.
+     * This includes both read permissions on the specific browser and list permissions on all browsers.
+     *
+     * @param grantee - The IAM principal to grant read permissions to
+     * @default - Default grant configuration:
+     * - actions: ['bedrock-agentcore:GetBrowser', 'bedrock-agentcore:GetBrowserSession'] on this.browserArn
+     * - actions: ['bedrock-agentcore:ListBrowsers', 'bedrock-agentcore:ListBrowserSessions'] on all resources (*)
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grantRead(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant invoke permissions on this browser to an IAM principal.
+     *
+     * @param grantee - The IAM principal to grant invoke permissions to
+     * @default - Default grant configuration:
+     * - actions: ['bedrock-agentcore:StartBrowserSession', 'bedrock-agentcore:UpdateBrowserStream', 'bedrock-agentcore:StopBrowserSession']
+     * - resourceArns: [this.browserArn]
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grantUse(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Return the given named metric for this browser.
+     *
+     * By default, the metric will be calculated as a sum over a period of 5 minutes.
+     * You can customize this by using the `statistic` and `period` properties.
+     */
+    metric(metricName: string, dimensions: DimensionsMap, props?: MetricOptions): Metric;
+    /**
+     * Creates a CloudWatch metric for tracking browser api operations..
+     *
+     * @param props - Configuration options for the metric
+     * @default - Default metric configuration:
+     * - namespace: 'AWS/Bedrock-AgentCore'
+     * - metricName: metricName
+     * - dimensionsMap: { BrowserId: this.browserId }
+     * @returns A CloudWatch Metric configured for browser api operations
+     */
+    metricForApiOperation(metricName: string, operation: string, props?: MetricOptions): Metric;
+    /**
+     * Creates a CloudWatch metric for tracking browser latencies.
+     *
+     * @param props - Configuration options for the metric
+     * @default - Default metric configuration:
+     * - namespace: 'AWS/Bedrock-AgentCore'
+     * - metricName: Latency
+     * @returns A CloudWatch Metric configured for browser latencies
+     */
+    metricLatencyForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Creates a CloudWatch metric for tracking browser invocations.
+     *
+     * @param props - Configuration options for the metric
+     * @default - Default metric configuration:
+     * - namespace: 'AWS/Bedrock-AgentCore'
+     * - metricName: Invocations
+     * @returns A CloudWatch Metric configured for browser latencies
+     */
+    metricInvocationsForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Creates a CloudWatch metric for tracking browser errors.
+     *
+     * @param props - Configuration options for the metric
+     * @default - Default metric configuration:
+     * - namespace: 'AWS/Bedrock-AgentCore'
+     * - metricName: Errors
+     * @returns A CloudWatch Metric configured for browser errors
+     */
+    metricErrorsForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Creates a CloudWatch metric for tracking browser throttles.
+     *
+     * @param props - Configuration options for the metric
+     * @default - Default metric configuration:
+     * - namespace: 'AWS/Bedrock-AgentCore'
+     * - metricName: Throttles
+     * @returns A CloudWatch Metric configured for browser throttles
+     */
+    metricThrottlesForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Creates a CloudWatch metric for tracking browser system errors.
+     *
+     * @param props - Configuration options for the metric
+     * @default - Default metric configuration:
+     * - namespace: 'AWS/Bedrock-AgentCore'
+     * - metricName: SystemErrors
+     * @returns A CloudWatch Metric configured for browser system errors
+     */
+    metricSystemErrorsForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Creates a CloudWatch metric for tracking browser user errors.
+     *
+     * @param props - Configuration options for the metric
+     * @default - Default metric configuration:
+     * - namespace: 'AWS/Bedrock-AgentCore'
+     * - metricName: UserErrors
+     * @returns A CloudWatch Metric configured for browser user errors
+     */
+    metricUserErrorsForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Creates a CloudWatch metric for tracking browser session duration.
+     *
+     * @param props - Configuration options for the metric
+     * @default - Default metric configuration:
+     * - namespace: 'AWS/Bedrock-AgentCore'
+     * - metricName: Duration
+     * @returns A CloudWatch Metric configured for browser session duration
+     */
+    metricSessionDuration(props?: MetricOptions): Metric;
+    /**
+     * Creates a CloudWatch metric for tracking browser user takeovers.
+     *
+     * @param props - Configuration options for the metric
+     * @default - Default metric configuration:
+     * - namespace: 'AWS/Bedrock-AgentCore'
+     * - metricName: TakeOverCount
+     * @returns A CloudWatch Metric configured for browser user takeovers
+     */
+    metricTakeOverCount(props?: MetricOptions): Metric;
+    /**
+     * Creates a CloudWatch metric for tracking browser user takeovers released.
+     *
+     * @param props - Configuration options for the metric
+     * @default - Default metric configuration:
+     * - namespace: 'AWS/Bedrock-AgentCore'
+     * - metricName: TakeOverReleaseCount
+     * @returns A CloudWatch Metric configured for browser user takeovers released
+     */
+    metricTakeOverReleaseCount(props?: MetricOptions): Metric;
+    /**
+     * Creates a CloudWatch metric for tracking browser user takeovers duration.
+     *
+     * @param props - Configuration options for the metric
+     * @default - Default metric configuration:
+     * - namespace: 'AWS/Bedrock-AgentCore'
+     * - metricName: TakeOverDuration
+     * @returns A CloudWatch Metric configured for browser user takeovers duration
+     */
+    metricTakeOverDuration(props?: MetricOptions): Metric;
+    /**
+     * Internal method to create a metric.
+     *
+     * @param props - Configuration options for the metric
+     * @returns A CloudWatch Metric configured for browser api operations
+     */
+    private configureMetric;
+}
+/******************************************************************************
+ *                                Recording Configuration
+ *****************************************************************************/
+/**
+ * Recording configuration for browser
+ */
+export interface RecordingConfig {
+    /**
+     * Whether recording is enabled
+     * @default - false
+     */
+    readonly enabled?: boolean;
+    /**
+     * S3 Location Configuration
+     * @default - undefined
+     */
+    readonly s3Location?: Location;
+}
+/******************************************************************************
+ *                        PROPS FOR NEW CONSTRUCT
+ *****************************************************************************/
+/**
+ * Properties for creating a Browser resource
+ */
+export interface BrowserCustomProps {
+    /**
+     * The name of the browser
+     * Valid characters are a-z, A-Z, 0-9, _ (underscore)
+     * The name must start with a letter and can be up to 48 characters long
+     * Pattern: [a-zA-Z][a-zA-Z0-9_]{0,47}
+     * @required - Yes
+     */
+    readonly browserCustomName: string;
+    /**
+     * Optional description for the browser
+     * Valid characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and spaces
+     * The description can have up to 200 characters
+     * @default - No description
+     * @required - No
+     */
+    readonly description?: string;
+    /**
+     * Network configuration for browser
+     * @required - No
+     * @default - PUBLIC network mode
+     */
+    readonly networkConfiguration?: BrowserNetworkConfiguration;
+    /**
+     * Recording configuration for browser
+     * @required - No
+     * @default - No recording configuration
+     */
+    readonly recordingConfig?: RecordingConfig;
+    /**
+     * The IAM role that provides permissions for the browser to access AWS services
+     * @default - A new role will be created
+     * @required - No
+     */
+    readonly executionRole?: iam.IRole;
+    /**
+     * Tags (optional)
+     * A list of key:value pairs of tags to apply to this Browser resource
+     *
+     * @default {} - no tags
+     * @required - No
+     */
+    readonly tags?: {
+        [key: string]: string;
+    };
+}
+/******************************************************************************
+ *                      ATTRS FOR IMPORTED CONSTRUCT
+ *****************************************************************************/
+/**
+ * Attributes for specifying an imported Browser Custom.
+ */
+export interface BrowserCustomAttributes {
+    /**
+     * The ARN of the agent.
+     * @attribute
+     */
+    readonly browserArn: string;
+    /**
+     * The ARN of the IAM role associated to the browser.
+     * @attribute
+     */
+    readonly roleArn: string;
+    /**
+     * When this browser was last updated.
+     * @default undefined - No last updated timestamp is provided
+     */
+    readonly lastUpdatedAt?: string;
+    /**
+     * The status of the browser.
+     * @default undefined - No status is provided
+     */
+    readonly status?: string;
+    /**
+     * The created timestamp of the browser.
+     * @default undefined - No created timestamp is provided
+     */
+    readonly createdAt?: string;
+    /**
+     * The security groups for this browser, if in a VPC.
+     *
+     * @default - By default, the browser is not in a VPC.
+     */
+    readonly securityGroups?: ec2.ISecurityGroup[];
+}
+/******************************************************************************
+ *                                Class
+ *****************************************************************************/
+/**
+ * Browser resource for AWS Bedrock Agent Core.
+ * Provides a browser environment for web automation and interaction.
+ *
+ * @see https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser.html
+ * @resource AWS::BedrockAgentCore::BrowserCustom
+ */
+export declare class BrowserCustom extends BrowserCustomBase {
+    /** Uniquely identifies this class. */
+    static readonly PROPERTY_INJECTION_ID: string;
+    /**
+     * Static Method for importing an existing Bedrock AgentCore Browser Custom.
+     */
+    /**
+     * Creates an Browser Custom reference from an existing browser's attributes.
+     *
+     * @param scope - The construct scope
+     * @param id - Identifier of the construct
+     * @param attrs - Attributes of the existing browser custom
+     * @returns An IBrowserCustom reference to the existing browser
+     */
+    static fromBrowserCustomAttributes(scope: Construct, id: string, attrs: BrowserCustomAttributes): IBrowserCustom;
+    /**
+     * The ARN of the browser resource.
+     * @attribute
+     */
+    readonly browserArn: string;
+    /**
+     * The id of the browser
+     * @attribute
+     */
+    readonly browserId: string;
+    /**
+     * The name of the browser
+     */
+    readonly name: string;
+    /**
+     * The description of the browser
+     */
+    readonly description?: string;
+    /**
+     * The last updated timestamp of the browser
+     * @attribute
+     */
+    readonly lastUpdatedAt?: string;
+    /**
+     * The status of the browser
+     * @attribute
+     */
+    readonly status?: string;
+    /**
+     * The created timestamp of the browser
+     * @attribute
+     */
+    readonly createdAt?: string;
+    /**
+     * The failure reason of the browser
+     * @attribute
+     */
+    readonly failureReason?: string;
+    /**
+     * The IAM role associated to the browser.
+     */
+    readonly executionRole: iam.IRole;
+    /**
+     * Tags applied to this browser resource
+     * A map of key-value pairs for resource tagging
+     * @default - No tags applied
+     */
+    readonly tags?: {
+        [key: string]: string;
+    };
+    /**
+     * The principal to grant permissions to
+     */
+    readonly grantPrincipal: iam.IPrincipal;
+    /**
+     * The network configuration of the browser
+     */
+    readonly networkConfiguration: BrowserNetworkConfiguration;
+    /**
+     * The recording configuration of the browser
+     */
+    readonly recordingConfig?: RecordingConfig;
+    private readonly __resource;
+    constructor(scope: Construct, id: string, props: BrowserCustomProps);
+    /**
+     * Render the recording configuration.
+     *
+     * @returns RecordingConfigProperty object in CloudFormation format, or undefined if no recording configuration is defined
+     * @default - undefined if no recording configuration is provided
+     * @internal This is an internal core function and should not be called directly.
+     */
+    private _renderRecordingConfig;
+    /**
+     * Creates execution role needed for the browser to access AWS services
+     * @returns The created role
+     * @internal This is an internal core function and should not be called directly.
+     */
+    private _createBrowserRole;
+    /**
+     * Validates the browser name format
+     * @param name The browser name to validate
+     * @returns Array of validation error messages, empty if valid
+     */
+    private _validateBrowserName;
+    /**
+     * Validates the browser tags format
+     * @param tags The tags object to validate
+     * @returns Array of validation error messages, empty if valid
+     */
+    private _validateBrowserTags;
+    /**
+     * Validates the recording configuration
+     * @param recordingConfig The recording configuration to validate
+     * @returns Array of validation error messages, empty if valid
+     */
+    private _validateRecordingConfig;
+}