codepipeline-event-notifier 0.1.7 → 0.2.0

package/.jsii

@@ -8455,7 +8455,7 @@
   },
   "name": "codepipeline-event-notifier",
   "readme": {
-    "markdown": "# CodePipeline Event Notifier\n\n[![npm version](https://img.shields.io/npm/v/codepipeline-event-notifier.svg)](https://www.npmjs.com/package/codepipeline-event-notifier)\n[![license](https://img.shields.io/npm/l/codepipeline-event-notifier.svg)](LICENSE)\n\nCDK construct that listens to **AWS CodePipeline execution STARTED** events via EventBridge, invokes a Lambda notifier, and publishes execution state changes to an SNS topic.\n\n## Features\n\n- **EventBridge integration**: triggers on `CodePipeline Pipeline Execution State Change` with `state=STARTED`\n- **SNS notifications**: publishes execution status transitions (observed while polling) as JSON messages\n- **Execution polling**: polls `GetPipelineExecution` until a terminal state or timeout\n- **No subscriptions by default**: the SNS Topic is created, but subscriptions (email/HTTP/etc.) are intentionally not configured\n\n## Installation\n\n### npm\n\n```bash\nnpm install codepipeline-event-notifier\n```\n\n### yarn\n\n```bash\nyarn add codepipeline-event-notifier\n```\n\n## Usage\n\nInstantiate `CodePipelineEventNotifier` in your CDK stack:\n\n```ts\nimport { Stack } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { CodePipelineEventNotifier } from 'codepipeline-event-notifier';\n\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string) {\n    super(scope, id);\n\n    new CodePipelineEventNotifier(this, 'CodePipelineEventNotifier');\n  }\n}\n```\n\n## Options\n\nThe notifier Lambda supports the following environment variables:\n\n- `SNS_TOPIC_ARN` (**required**): SNS topic ARN to publish notifications to (provided by the construct)\n- `POLL_INTERVAL_SECONDS` (default: `10`): poll interval in seconds\n- `MAX_POLL_MINUTES` (default: `14`): maximum polling duration in minutes (Lambda should be configured with a matching timeout)\n\n## Requirements\n\n- Node.js `>= 20`\n- AWS CDK `v2` (`aws-cdk-lib`)\n\n## License\n\nThis project is licensed under the Apache-2.0 License."
+    "markdown": "# CodePipeline Event Notifier\n\n[![npm version](https://img.shields.io/npm/v/codepipeline-event-notifier.svg)](https://www.npmjs.com/package/codepipeline-event-notifier)\n[![license](https://img.shields.io/npm/l/codepipeline-event-notifier.svg)](LICENSE)\n\nCDK construct that listens to **AWS CodePipeline execution STARTED** events via EventBridge, invokes a Lambda notifier, and publishes execution state changes to an SNS topic.\n\n## Features\n\n- **EventBridge integration**: triggers on `CodePipeline Pipeline Execution State Change` with `state=STARTED` (customizable via `eventPattern`)\n- **SNS notifications**: publishes execution status transitions as JSON messages (`phase`: `eventbridge` / `wait`)\n- **Execution waiting**: calls `GetPipelineExecution` until a terminal state (`SUCCEEDED` / `FAILED` / `STOPPED` / `SUPERSEDED`) or timeout\n- **Configurable props**: reuse an existing SNS topic, adjust wait interval / max wait duration / Lambda timeout, and filter events\n- **No subscriptions by default**: the SNS topic is created (or reused), but subscriptions (email/HTTP/etc.) are intentionally not configured\n\n## Installation\n\n### npm\n\n```bash\nnpm install codepipeline-event-notifier\n```\n\n### yarn\n\n```bash\nyarn add codepipeline-event-notifier\n```\n\n## Usage\n\nInstantiate `CodePipelineEventNotifier` in your CDK stack:\n\n```ts\nimport { Stack } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { CodePipelineEventNotifier } from 'codepipeline-event-notifier';\n\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string) {\n    super(scope, id);\n\n    const notifier = new CodePipelineEventNotifier(this, 'CodePipelineEventNotifier');\n\n    // Optionally subscribe to the topic created by the construct\n    // notifier.topic.addSubscription(...);\n  }\n}\n```\n\n### Customize with props\n\n```ts\nimport { Duration, Stack, aws_sns as sns } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { CodePipelineEventNotifier } from 'codepipeline-event-notifier';\n\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string) {\n    super(scope, id);\n\n    const topic = sns.Topic.fromTopicArn(this, 'ExistingTopic', 'arn:aws:sns:...');\n\n    new CodePipelineEventNotifier(this, 'CodePipelineEventNotifier', {\n      topic,\n      waitInterval: Duration.seconds(30),\n      maxWaitDuration: Duration.minutes(10),\n      timeout: Duration.minutes(12),\n      eventPattern: {\n        source: ['aws.codepipeline'],\n        detailType: ['CodePipeline Pipeline Execution State Change'],\n        detail: {\n          state: ['STARTED'],\n          pipeline: ['my-pipeline'],\n        },\n      },\n    });\n  }\n}\n```\n\n## Options\n\n| Prop | Type | Default | Description |\n| --- | --- | --- | --- |\n| `topic` | `sns.ITopic` | new topic | SNS topic to publish notifications to (also exposed as `notifier.topic`) |\n| `waitInterval` | `Duration` | `10 seconds` | Interval between `GetPipelineExecution` calls |\n| `maxWaitDuration` | `Duration` | `14 minutes` | Maximum wait duration before giving up |\n| `timeout` | `Duration` | `15 minutes` | Notifier Lambda timeout (should exceed `maxWaitDuration`) |\n| `eventPattern` | `events.EventPattern` | CodePipeline `STARTED` | EventBridge rule filter |\n\nThe notifier Lambda uses these environment variables (set by the construct from props):\n\n- `SNS_TOPIC_ARN` (**required**): SNS topic ARN to publish notifications to\n- `WAIT_INTERVAL_SECONDS` (default: `10`): wait interval in seconds\n- `MAX_WAIT_MINUTES` (default: `14`): maximum wait duration in minutes\n\n## Requirements\n\n- Node.js `>= 20`\n- AWS CDK `v2` (`aws-cdk-lib` `^2.232.0`)\n- `constructs` `^10.5.1`\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n"
   },
   "repository": {
     "type": "git",
@@ -8468,43 +8468,190 @@
     }
   },
   "types": {
-    "codepipeline-event-notifier.Hello": {
+    "codepipeline-event-notifier.CodePipelineEventNotifier": {
       "assembly": "codepipeline-event-notifier",
+      "base": "constructs.Construct",
       "docs": {
-        "stability": "stable"
+        "stability": "stable",
+        "summary": "Provisions an EventBridge rule that listens for CodePipeline execution STARTED events, then invokes a notifier Lambda which publishes execution state changes to an SNS topic."
       },
-      "fqn": "codepipeline-event-notifier.Hello",
+      "fqn": "codepipeline-event-notifier.CodePipelineEventNotifier",
       "initializer": {
         "docs": {
           "stability": "stable"
-        }
+        },
+        "locationInModule": {
+          "filename": "src/constructs/codepipeline-event-notifier.ts",
+          "line": 63
+        },
+        "parameters": [
+          {
+            "docs": {
+              "summary": "the construct scope."
+            },
+            "name": "scope",
+            "type": {
+              "fqn": "constructs.Construct"
+            }
+          },
+          {
+            "docs": {
+              "summary": "the construct id."
+            },
+            "name": "id",
+            "type": {
+              "primitive": "string"
+            }
+          },
+          {
+            "docs": {
+              "summary": "construct properties."
+            },
+            "name": "props",
+            "optional": true,
+            "type": {
+              "fqn": "codepipeline-event-notifier.CodePipelineEventNotifierProps"
+            }
+          }
+        ]
       },
       "kind": "class",
       "locationInModule": {
-        "filename": "src/index.ts",
-        "line": 1
+        "filename": "src/constructs/codepipeline-event-notifier.ts",
+        "line": 52
       },
-      "methods": [
+      "name": "CodePipelineEventNotifier",
+      "properties": [
         {
           "docs": {
-            "stability": "stable"
+            "stability": "stable",
+            "summary": "SNS topic that receives CodePipeline execution notifications."
           },
+          "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 2
+            "filename": "src/constructs/codepipeline-event-notifier.ts",
+            "line": 56
           },
-          "name": "sayHello",
-          "returns": {
-            "type": {
-              "primitive": "string"
-            }
+          "name": "topic",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_sns.ITopic"
+          }
+        }
+      ],
+      "symbolId": "src/constructs/codepipeline-event-notifier:CodePipelineEventNotifier"
+    },
+    "codepipeline-event-notifier.CodePipelineEventNotifierProps": {
+      "assembly": "codepipeline-event-notifier",
+      "datatype": true,
+      "docs": {
+        "stability": "stable",
+        "summary": "Properties for {@link CodePipelineEventNotifier}."
+      },
+      "fqn": "codepipeline-event-notifier.CodePipelineEventNotifierProps",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/constructs/codepipeline-event-notifier.ts",
+        "line": 8
+      },
+      "name": "CodePipelineEventNotifierProps",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "default": "CodePipeline Pipeline Execution State Change with `state=STARTED`",
+            "stability": "stable",
+            "summary": "EventBridge event pattern that triggers the notifier."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/codepipeline-event-notifier.ts",
+            "line": 45
+          },
+          "name": "eventPattern",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_events.EventPattern"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "Duration.minutes(14)",
+            "remarks": "Mapped to the notifier Lambda environment variable `MAX_WAIT_MINUTES`.",
+            "stability": "stable",
+            "summary": "Maximum duration to wait for execution state changes."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/codepipeline-event-notifier.ts",
+            "line": 30
+          },
+          "name": "maxWaitDuration",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.Duration"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "Duration.minutes(15)",
+            "remarks": "Should be greater than {@link maxWaitDuration}.",
+            "stability": "stable",
+            "summary": "Timeout for the notifier Lambda function."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/codepipeline-event-notifier.ts",
+            "line": 38
+          },
+          "name": "timeout",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.Duration"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- a new topic is created",
+            "remarks": "Subscriptions (email/HTTP/etc.) are intentionally not managed by this construct.",
+            "stability": "stable",
+            "summary": "SNS topic that receives CodePipeline execution notifications."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/codepipeline-event-notifier.ts",
+            "line": 15
+          },
+          "name": "topic",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_sns.ITopic"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "Duration.seconds(10)",
+            "stability": "stable",
+            "summary": "Interval between `GetPipelineExecution` waits."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/codepipeline-event-notifier.ts",
+            "line": 22
+          },
+          "name": "waitInterval",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.Duration"
           }
         }
       ],
-      "name": "Hello",
-      "symbolId": "src/index:Hello"
+      "symbolId": "src/constructs/codepipeline-event-notifier:CodePipelineEventNotifierProps"
     }
   },
-  "version": "0.1.7",
-  "fingerprint": "mJVXyO/9eL1ztCNPuqsMeOz6GfUBeFxNpa7938zaIR4="
+  "version": "0.2.0",
+  "fingerprint": "haiP7ZcLzAoufXc8v9n0DlrCNnVW5pL8h+9noaJvwW4="
 }

package/API.md

@@ -1,21 +1,48 @@
 # API Reference <a name="API Reference" id="api-reference"></a>
 
+## Constructs <a name="Constructs" id="Constructs"></a>
 
+### CodePipelineEventNotifier <a name="CodePipelineEventNotifier" id="codepipeline-event-notifier.CodePipelineEventNotifier"></a>
 
-## Classes <a name="Classes" id="Classes"></a>
+Provisions an EventBridge rule that listens for CodePipeline execution STARTED events, then invokes a notifier Lambda which publishes execution state changes to an SNS topic.
 
-### Hello <a name="Hello" id="codepipeline-event-notifier.Hello"></a>
-
-#### Initializers <a name="Initializers" id="codepipeline-event-notifier.Hello.Initializer"></a>
+#### Initializers <a name="Initializers" id="codepipeline-event-notifier.CodePipelineEventNotifier.Initializer"></a>
 
 ```typescript
-import { Hello } from 'codepipeline-event-notifier'
+import { CodePipelineEventNotifier } from 'codepipeline-event-notifier'
 
-new Hello()
+new CodePipelineEventNotifier(scope: Construct, id: string, props?: CodePipelineEventNotifierProps)
 ```
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifier.Initializer.parameter.scope">scope</a></code> | <code>constructs.Construct</code> | the construct scope. |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifier.Initializer.parameter.id">id</a></code> | <code>string</code> | the construct id. |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifier.Initializer.parameter.props">props</a></code> | <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifierProps">CodePipelineEventNotifierProps</a></code> | construct properties. |
+
+---
+
+##### `scope`<sup>Required</sup> <a name="scope" id="codepipeline-event-notifier.CodePipelineEventNotifier.Initializer.parameter.scope"></a>
+
+- *Type:* constructs.Construct
+
+the construct scope.
+
+---
+
+##### `id`<sup>Required</sup> <a name="id" id="codepipeline-event-notifier.CodePipelineEventNotifier.Initializer.parameter.id"></a>
+
+- *Type:* string
+
+the construct id.
+
+---
+
+##### `props`<sup>Optional</sup> <a name="props" id="codepipeline-event-notifier.CodePipelineEventNotifier.Initializer.parameter.props"></a>
+
+- *Type:* <a href="#codepipeline-event-notifier.CodePipelineEventNotifierProps">CodePipelineEventNotifierProps</a>
+
+construct properties.
 
 ---
 
@@ -23,17 +50,210 @@ new Hello()
 
 | **Name** | **Description** |
 | --- | --- |
-| <code><a href="#codepipeline-event-notifier.Hello.sayHello">sayHello</a></code> | *No description.* |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifier.toString">toString</a></code> | Returns a string representation of this construct. |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifier.with">with</a></code> | Applies one or more mixins to this construct. |
 
 ---
 
-##### `sayHello` <a name="sayHello" id="codepipeline-event-notifier.Hello.sayHello"></a>
+##### `toString` <a name="toString" id="codepipeline-event-notifier.CodePipelineEventNotifier.toString"></a>
 
 ```typescript
-public sayHello(): string
+public toString(): string
 ```
 
+Returns a string representation of this construct.
 
+##### `with` <a name="with" id="codepipeline-event-notifier.CodePipelineEventNotifier.with"></a>
+
+```typescript
+public with(mixins: ...IMixin[]): IConstruct
+```
+
+Applies one or more mixins to this construct.
+
+Mixins are applied in order. The list of constructs is captured at the
+start of the call, so constructs added by a mixin will not be visited.
+Use multiple `with()` calls if subsequent mixins should apply to added
+constructs.
+
+###### `mixins`<sup>Required</sup> <a name="mixins" id="codepipeline-event-notifier.CodePipelineEventNotifier.with.parameter.mixins"></a>
+
+- *Type:* ...constructs.IMixin[]
+
+The mixins to apply.
+
+---
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifier.isConstruct">isConstruct</a></code> | Checks if `x` is a construct. |
+
+---
+
+##### `isConstruct` <a name="isConstruct" id="codepipeline-event-notifier.CodePipelineEventNotifier.isConstruct"></a>
+
+```typescript
+import { CodePipelineEventNotifier } from 'codepipeline-event-notifier'
+
+CodePipelineEventNotifier.isConstruct(x: any)
+```
+
+Checks if `x` is a construct.
+
+Use this method instead of `instanceof` to properly detect `Construct`
+instances, even when the construct library is symlinked.
+
+Explanation: in JavaScript, multiple copies of the `constructs` library on
+disk are seen as independent, completely different libraries. As a
+consequence, the class `Construct` in each copy of the `constructs` library
+is seen as a different class, and an instance of one class will not test as
+`instanceof` the other class. `npm install` will not create installations
+like this, but users may manually symlink construct libraries together or
+use a monorepo tool: in those cases, multiple copies of the `constructs`
+library can be accidentally installed, and `instanceof` will behave
+unpredictably. It is safest to avoid using `instanceof`, and using
+this type-testing method instead.
+
+###### `x`<sup>Required</sup> <a name="x" id="codepipeline-event-notifier.CodePipelineEventNotifier.isConstruct.parameter.x"></a>
+
+- *Type:* any
+
+Any object.
+
+---
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifier.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifier.property.topic">topic</a></code> | <code>aws-cdk-lib.aws_sns.ITopic</code> | SNS topic that receives CodePipeline execution notifications. |
+
+---
+
+##### `node`<sup>Required</sup> <a name="node" id="codepipeline-event-notifier.CodePipelineEventNotifier.property.node"></a>
+
+```typescript
+public readonly node: Node;
+```
+
+- *Type:* constructs.Node
+
+The tree node.
+
+---
+
+##### `topic`<sup>Required</sup> <a name="topic" id="codepipeline-event-notifier.CodePipelineEventNotifier.property.topic"></a>
+
+```typescript
+public readonly topic: ITopic;
+```
+
+- *Type:* aws-cdk-lib.aws_sns.ITopic
+
+SNS topic that receives CodePipeline execution notifications.
+
+---
+
+
+## Structs <a name="Structs" id="Structs"></a>
+
+### CodePipelineEventNotifierProps <a name="CodePipelineEventNotifierProps" id="codepipeline-event-notifier.CodePipelineEventNotifierProps"></a>
+
+Properties for {@link CodePipelineEventNotifier}.
+
+#### Initializer <a name="Initializer" id="codepipeline-event-notifier.CodePipelineEventNotifierProps.Initializer"></a>
+
+```typescript
+import { CodePipelineEventNotifierProps } from 'codepipeline-event-notifier'
+
+const codePipelineEventNotifierProps: CodePipelineEventNotifierProps = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifierProps.property.eventPattern">eventPattern</a></code> | <code>aws-cdk-lib.aws_events.EventPattern</code> | EventBridge event pattern that triggers the notifier. |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifierProps.property.maxWaitDuration">maxWaitDuration</a></code> | <code>aws-cdk-lib.Duration</code> | Maximum duration to wait for execution state changes. |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifierProps.property.timeout">timeout</a></code> | <code>aws-cdk-lib.Duration</code> | Timeout for the notifier Lambda function. |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifierProps.property.topic">topic</a></code> | <code>aws-cdk-lib.aws_sns.ITopic</code> | SNS topic that receives CodePipeline execution notifications. |
+| <code><a href="#codepipeline-event-notifier.CodePipelineEventNotifierProps.property.waitInterval">waitInterval</a></code> | <code>aws-cdk-lib.Duration</code> | Interval between `GetPipelineExecution` waits. |
+
+---
+
+##### `eventPattern`<sup>Optional</sup> <a name="eventPattern" id="codepipeline-event-notifier.CodePipelineEventNotifierProps.property.eventPattern"></a>
+
+```typescript
+public readonly eventPattern: EventPattern;
+```
+
+- *Type:* aws-cdk-lib.aws_events.EventPattern
+- *Default:* CodePipeline Pipeline Execution State Change with `state=STARTED`
+
+EventBridge event pattern that triggers the notifier.
+
+---
+
+##### `maxWaitDuration`<sup>Optional</sup> <a name="maxWaitDuration" id="codepipeline-event-notifier.CodePipelineEventNotifierProps.property.maxWaitDuration"></a>
+
+```typescript
+public readonly maxWaitDuration: Duration;
+```
+
+- *Type:* aws-cdk-lib.Duration
+- *Default:* Duration.minutes(14)
+
+Maximum duration to wait for execution state changes.
+
+Mapped to the notifier Lambda environment variable `MAX_WAIT_MINUTES`.
+
+---
+
+##### `timeout`<sup>Optional</sup> <a name="timeout" id="codepipeline-event-notifier.CodePipelineEventNotifierProps.property.timeout"></a>
+
+```typescript
+public readonly timeout: Duration;
+```
+
+- *Type:* aws-cdk-lib.Duration
+- *Default:* Duration.minutes(15)
+
+Timeout for the notifier Lambda function.
+
+Should be greater than {@link maxWaitDuration}.
+
+---
+
+##### `topic`<sup>Optional</sup> <a name="topic" id="codepipeline-event-notifier.CodePipelineEventNotifierProps.property.topic"></a>
+
+```typescript
+public readonly topic: ITopic;
+```
+
+- *Type:* aws-cdk-lib.aws_sns.ITopic
+- *Default:* a new topic is created
+
+SNS topic that receives CodePipeline execution notifications.
+
+Subscriptions (email/HTTP/etc.) are intentionally not managed by this construct.
+
+---
+
+##### `waitInterval`<sup>Optional</sup> <a name="waitInterval" id="codepipeline-event-notifier.CodePipelineEventNotifierProps.property.waitInterval"></a>
+
+```typescript
+public readonly waitInterval: Duration;
+```
+
+- *Type:* aws-cdk-lib.Duration
+- *Default:* Duration.seconds(10)
+
+Interval between `GetPipelineExecution` waits.
+
+---
 
 
 

package/README.md

@@ -7,10 +7,11 @@ CDK construct that listens to **AWS CodePipeline execution STARTED** events via
 
 ## Features
 
-- **EventBridge integration**: triggers on `CodePipeline Pipeline Execution State Change` with `state=STARTED`
-- **SNS notifications**: publishes execution status transitions (observed while polling) as JSON messages
-- **Execution polling**: polls `GetPipelineExecution` until a terminal state or timeout
-- **No subscriptions by default**: the SNS Topic is created, but subscriptions (email/HTTP/etc.) are intentionally not configured
+- **EventBridge integration**: triggers on `CodePipeline Pipeline Execution State Change` with `state=STARTED` (customizable via `eventPattern`)
+- **SNS notifications**: publishes execution status transitions as JSON messages (`phase`: `eventbridge` / `wait`)
+- **Execution waiting**: calls `GetPipelineExecution` until a terminal state (`SUCCEEDED` / `FAILED` / `STOPPED` / `SUPERSEDED`) or timeout
+- **Configurable props**: reuse an existing SNS topic, adjust wait interval / max wait duration / Lambda timeout, and filter events
+- **No subscriptions by default**: the SNS topic is created (or reused), but subscriptions (email/HTTP/etc.) are intentionally not configured
 
 ## Installation
 
@@ -39,24 +40,67 @@ export class MyStack extends Stack {
   constructor(scope: Construct, id: string) {
     super(scope, id);
 
-    new CodePipelineEventNotifier(this, 'CodePipelineEventNotifier');
+    const notifier = new CodePipelineEventNotifier(this, 'CodePipelineEventNotifier');
+
+    // Optionally subscribe to the topic created by the construct
+    // notifier.topic.addSubscription(...);
+  }
+}
+```
+
+### Customize with props
+
+```ts
+import { Duration, Stack, aws_sns as sns } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { CodePipelineEventNotifier } from 'codepipeline-event-notifier';
+
+export class MyStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    const topic = sns.Topic.fromTopicArn(this, 'ExistingTopic', 'arn:aws:sns:...');
+
+    new CodePipelineEventNotifier(this, 'CodePipelineEventNotifier', {
+      topic,
+      waitInterval: Duration.seconds(30),
+      maxWaitDuration: Duration.minutes(10),
+      timeout: Duration.minutes(12),
+      eventPattern: {
+        source: ['aws.codepipeline'],
+        detailType: ['CodePipeline Pipeline Execution State Change'],
+        detail: {
+          state: ['STARTED'],
+          pipeline: ['my-pipeline'],
+        },
+      },
+    });
   }
 }
 ```
 
 ## Options
 
-The notifier Lambda supports the following environment variables:
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `topic` | `sns.ITopic` | new topic | SNS topic to publish notifications to (also exposed as `notifier.topic`) |
+| `waitInterval` | `Duration` | `10 seconds` | Interval between `GetPipelineExecution` calls |
+| `maxWaitDuration` | `Duration` | `14 minutes` | Maximum wait duration before giving up |
+| `timeout` | `Duration` | `15 minutes` | Notifier Lambda timeout (should exceed `maxWaitDuration`) |
+| `eventPattern` | `events.EventPattern` | CodePipeline `STARTED` | EventBridge rule filter |
+
+The notifier Lambda uses these environment variables (set by the construct from props):
 
-- `SNS_TOPIC_ARN` (**required**): SNS topic ARN to publish notifications to (provided by the construct)
-- `POLL_INTERVAL_SECONDS` (default: `10`): poll interval in seconds
-- `MAX_POLL_MINUTES` (default: `14`): maximum polling duration in minutes (Lambda should be configured with a matching timeout)
+- `SNS_TOPIC_ARN` (**required**): SNS topic ARN to publish notifications to
+- `WAIT_INTERVAL_SECONDS` (default: `10`): wait interval in seconds
+- `MAX_WAIT_MINUTES` (default: `14`): maximum wait duration in minutes
 
 ## Requirements
 
 - Node.js `>= 20`
-- AWS CDK `v2` (`aws-cdk-lib`)
+- AWS CDK `v2` (`aws-cdk-lib` `^2.232.0`)
+- `constructs` `^10.5.1`
 
 ## License
 
-This project is licensed under the Apache-2.0 License.
+This project is licensed under the Apache-2.0 License.