@composurecdk/lambda 0.11.2 → 0.12.1

package/README.md

@@ -174,21 +174,21 @@ Opt back into CDK's auto-created role attached to `AWSLambdaBasicExecutionRole`.
 
 The builder creates [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda) by default. No alarm actions are configured — access alarms from the build result to add SNS topics or other actions.
 
-| Alarm                    | Metric                            | Default threshold           | Created when                           |
-| ------------------------ | --------------------------------- | --------------------------- | -------------------------------------- |
-| `errors`                 | Errors (Sum, 1 min)               | > 0                         | Always                                 |
-| `throttles`              | Throttles (Sum, 1 min)            | > 0                         | Always                                 |
-| `duration`               | Duration (p99, 1 min)             | > 90% of configured timeout | `timeout` is set                       |
-| `concurrentExecutions`   | ConcurrentExecutions (Max, 1 min) | >= 80% of reserved limit    | `reservedConcurrentExecutions` is set  |
-| `<key>FailedInvocations` | FailedInvokeEventCount (Sum)      | > 0                         | An SQS or DynamoDB source is attached  |
-| `<key>DroppedEvents`     | DroppedEventCount (Sum)           | > 0                         | An SQS or DynamoDB source is attached  |
-| `iteratorAge`            | IteratorAge (Max, 1 min)          | > 60000 ms for 3 min¹       | A stream source (DynamoDB) is attached |
+| Alarm                    | Metric                            | Default threshold           | Created when                                      |
+| ------------------------ | --------------------------------- | --------------------------- | ------------------------------------------------- |
+| `errors`                 | Errors (Sum, 1 min)               | > 0                         | Always                                            |
+| `throttles`              | Throttles (Sum, 1 min)            | > 0                         | Always                                            |
+| `duration`               | Duration (p99, 1 min)             | > 90% of configured timeout | `timeout` is set                                  |
+| `concurrentExecutions`   | ConcurrentExecutions (Max, 1 min) | >= 80% of reserved limit    | `reservedConcurrentExecutions` is set             |
+| `<key>FailedInvocations` | FailedInvokeEventCount (Sum)      | > 0                         | An SQS, DynamoDB or Kinesis source is attached    |
+| `<key>DroppedEvents`     | DroppedEventCount (Sum)           | > 0                         | An SQS, DynamoDB or Kinesis source is attached    |
+| `iteratorAge`            | IteratorAge (Max, 1 min)          | > 60000 ms for 3 min¹       | A stream source (DynamoDB or Kinesis) is attached |
 
 ¹ AWS recommends alarming on `IteratorAge` for stream consumers but prescribes no fixed threshold — it is workload dependent. The 60s/3-minute default is deliberately conservative; tune it per workload via `eventSourceIteratorAge`.
 
 The per-mapping event-source alarms are contextual: one pair is created per event source attached via `addEventSource` (see [Event sources](#event-sources)) whose kind emits per-mapping ESM metrics. Each alarm's key is the event source's key suffixed with `FailedInvocations` / `DroppedEvents` — e.g. an event source added as `"orders"` produces `ordersFailedInvocations` and `ordersDroppedEvents`. The `eventSourceFailedInvocations` / `eventSourceDroppedEvents` fields on `recommendedAlarms` tune every such alarm.
 
-`iteratorAge` is different: `IteratorAge` is a function-level metric, so a single alarm (keyed `iteratorAge`) is created whenever at least one stream source (currently DynamoDB streams) is attached, regardless of how many. It warns when the consumer falls behind its stream. Tune or disable it via the `eventSourceIteratorAge` field on `recommendedAlarms`.
+`iteratorAge` is different: `IteratorAge` is a function-level metric, so a single alarm (keyed `iteratorAge`) is created whenever at least one stream source (DynamoDB streams or Kinesis, shared-throughput or enhanced fan-out) is attached, regardless of how many. It warns when the consumer falls behind its stream. Tune or disable it via the `eventSourceIteratorAge` field on `recommendedAlarms`.
 
 The defaults are exported as `FUNCTION_ALARM_DEFAULTS` for visibility and testing:
 
@@ -305,7 +305,7 @@ const system = compose(
 
 The source is attached _after_ the function and its least-privilege execution
 role exist, so the `source.bind(fn)` that `addEventSource` performs grants the
-consume permission (SQS `ReceiveMessage`, or DynamoDB `grantStreamRead`) onto
+consume permission (SQS `ReceiveMessage`, DynamoDB `grantStreamRead`, or Kinesis `grantRead`) onto
 the builder's role rather than CDK's auto-role.
 
 `dynamoEventSource(table, props?)` mirrors the SQS factory for DynamoDB streams.
@@ -356,7 +356,7 @@ second `props` argument and exported as `DEFAULT_SQS_EVENT_SOURCE_PROPS`:
 
 `dynamoEventSource` applies the same defaults plus `startingPosition` and
 `bisectBatchOnError`, exported as `DEFAULT_DYNAMO_EVENT_SOURCE_PROPS` (the shared
-`DEFAULT_STREAM_EVENT_SOURCE_PROPS`, which a future `kinesisEventSource` reuses):
+`DEFAULT_STREAM_EVENT_SOURCE_PROPS`, which the [Kinesis helpers](#kinesis-data-streams) share):
 
 | Property                  | Default                     | Rationale                                                                                                            |
 | ------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
@@ -404,9 +404,10 @@ way:
 )
 ```
 
-An S3 destination on a **DynamoDB stream** mapping needs **aws-cdk-lib ≥ 2.184.0**,
-above this package's [floor](../../docs/adr/0008-aws-cdk-lib-version-floors.md) of
-2.168.0. `DynamoEventSource` only opts into S3 destinations from that release;
+An S3 destination on a **DynamoDB stream** (or [Kinesis](#kinesis-data-streams))
+mapping needs **aws-cdk-lib ≥ 2.184.0**, above this package's
+[floor](../../docs/adr/0008-aws-cdk-lib-version-floors.md) of 2.180.0.
+`DynamoEventSource` only opts into S3 destinations from that release;
 below it CDK rejects the pairing at synth with `S3 onFailure Destination is not
 supported for this event source`. The limit is CDK's, not this package's — a
 queue destination works at the floor.
@@ -418,15 +419,122 @@ when dropping is intended — with
 
 ### Cross-component invariants
 
-AWS Well-Architected guidance spans the queue and the function — the source
-queue's visibility timeout should be ≥ 6× the function timeout, and its redrive
-`maxReceiveCount` should be ≥ 5 before the DLQ. These are **not** enforced
-today (the queue often arrives as an unresolved `ref()`); they are tracked in
-[#123](https://github.com/laazyj/composureCDK/issues/123) and
-[#124](https://github.com/laazyj/composureCDK/issues/124).
+AWS Well-Architected guidance spans the queue and the function. Both rules are
+suppressible synth-time warnings:
+
+- **Visibility timeout ≥ 6× the function timeout** — a relationship guard in
+  this package, checked even when the queue arrives as a `ref()` (see
+  [ADR-0011](../../docs/adr/0011-cross-component-relationship-guards.md)). It
+  stays quiet for imported queues and token values. Silence it with
+  `Annotations.of(scope).acknowledgeWarning(SQS_VISIBILITY_TIMEOUT_WARNING_ID)`.
+- **Redrive `maxReceiveCount` ≥ 5 before the DLQ** — checked by
+  `@composurecdk/sqs`'s `QueueBuilder`, so only for queues it builds. See
+  [its dead-letter docs](../sqs/README.md#dead-letter-queues-dlq-fifo-dlq) for
+  the warning id.
+
+### Kinesis Data Streams
+
+`kinesisEventSource(stream, props?)` attaches a Kinesis data stream through
+**shared-throughput** iterators; `kinesisConsumerEventSource(consumer, props?)`
+attaches it through a registered **enhanced fan-out** (EFO) consumer
+(`StreamConsumer`). Both take aws-cdk-lib types — concrete or a `ref()` to a
+sibling's output — and bind with the stream's (or consumer's) `grantRead`,
+which includes `kms:Decrypt` for a customer-managed key.
+
+To build the stream and its consumer as composed components, with
+well-architected defaults and recommended alarms, use `createStreamBuilder()`
+and `createStreamConsumerBuilder()` from [`@composurecdk/kinesis`](../kinesis/README.md)
+and pass `ref("stream", (r) => r.stream)` or `ref("consumer", (r) => r.consumer)`.
 
-`kinesisEventSource` is still deferred — see
-[#120](https://github.com/laazyj/composureCDK/issues/120).
+```ts
+import { Duration } from "aws-cdk-lib";
+import { Stream } from "aws-cdk-lib/aws-kinesis";
+import { compose, ref } from "@composurecdk/core";
+import { createFunctionBuilder, kinesisEventSource } from "@composurecdk/lambda";
+import { createQueueBuilder } from "@composurecdk/sqs";
+
+const telemetry = new Stream(stack, "Telemetry");
+
+compose(
+  {
+    dlq: createQueueBuilder("dlq"),
+    processor: createFunctionBuilder()
+      .runtime(Runtime.NODEJS_22_X)
+      .handler("index.handler")
+      .code(Code.fromAsset("lambda"))
+      .addEventSource(
+        "telemetry",
+        kinesisEventSource(telemetry, {
+          retryAttempts: 3,
+          maxRecordAge: Duration.hours(1),
+          onFailure: ref("dlq", (r) => r.queue),
+        }),
+      ),
+  },
+  { dlq: [], processor: ["dlq"] },
+);
+```
+
+Both apply `DEFAULT_KINESIS_EVENT_SOURCE_PROPS` — the same
+`DEFAULT_STREAM_EVENT_SOURCE_PROPS` as `dynamoEventSource`, each overridable via
+`props`:
+
+| Property                  | Default                     | Rationale                                                                                                            |
+| ------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `startingPosition`        | `LATEST`                    | A newly-attached consumer reads from the stream tip instead of replaying the whole retention window.                 |
+| `reportBatchItemFailures` | `true`                      | A single poison record fails only its own record, not the whole batch. CDK defaults this `false`.                    |
+| `bisectBatchOnError`      | `true`                      | Split and retry a failing batch, isolating a poison record instead of blocking the shard. CDK defaults this `false`. |
+| `metricsConfig`           | `{ metrics: [EventCount] }` | Enables the per-mapping ESM metrics that back the event-source contextual alarms.                                    |
+
+`startingPosition` is optional (CDK's `KinesisEventSourceProps` requires it);
+`AT_TIMESTAMP` also needs `startingPositionTimestamp`. Sources:
+[Lambda Kinesis parameters](https://docs.aws.amazon.com/lambda/latest/dg/services-kinesis-parameters.html),
+[batch item failures](https://docs.aws.amazon.com/lambda/latest/dg/services-kinesis-batchfailurereporting.html).
+
+**Failure handling and retention.** Lambda processes each shard in order, so by
+default a failing batch is retried until its records expire — blocking that
+shard for up to the stream's **retention period**: 24 h with CDK's `Stream`
+default, **7 days** with the `@composurecdk/kinesis` default. Bisecting isolates
+the poison record but does not stop it being retried. Bound `retryAttempts`
+and/or `maxRecordAge` **together with** `onFailure`, so a record that never
+succeeds is moved aside and the shard keeps flowing. `onFailure` is widened
+exactly as for `dynamoEventSource` — a queue (wrapped in `SqsDlq`), any
+`IEventSourceDlq` such as `SnsDlq` or `S3OnFailureDestination`, or a `ref()` to
+either — and the [`STREAM_DLQ_WARNING_ID`](#failure-handling-dead-letter-queue)
+warning fires when retries are bounded without one. The bound is not defaulted:
+bounding without a destination would drop records silently. A queue or topic
+destination receives the batch's metadata (shard and sequence-number range),
+not the records — read them back from the stream before they age out. An S3
+destination captures the whole batch, and needs **aws-cdk-lib ≥ 2.184.0**
+(below it CDK rejects it at synth, as for DynamoDB). See
+[on-failure destinations](https://docs.aws.amazon.com/lambda/latest/dg/kinesis-on-failure-destination.html).
+
+**Shared throughput or enhanced fan-out.** A shard's 2 MB/s of read throughput
+is shared by every shared-throughput consumer. An EFO consumer gets a dedicated
+2 MB/s per shard, pushed over HTTP/2 with lower propagation delay, and is
+billed per consumer-shard-hour and per GB retrieved. Use `kinesisEventSource`
+for one or a few consumers; reach for `kinesisConsumerEventSource` when several
+applications read the same stream or latency matters. See
+[enhanced fan-out consumers](https://docs.aws.amazon.com/streams/latest/dev/enhanced-consumers.html).
+
+```ts
+import { StreamConsumer } from "aws-cdk-lib/aws-kinesis";
+import { kinesisConsumerEventSource } from "@composurecdk/lambda";
+
+const consumer = new StreamConsumer(stack, "AlertsConsumer", {
+  streamConsumerName: "alerts",
+  stream: telemetry,
+});
+
+createFunctionBuilder()
+  // ...
+  .addEventSource("alerts", kinesisConsumerEventSource(consumer));
+```
+
+`KinesisConsumerEventSource` arrived in aws-cdk-lib 2.180.0, which sets this
+package's floor. Either helper adds the function-level `iteratorAge` alarm and
+the per-mapping `<key>FailedInvocations` / `<key>DroppedEvents` alarms (see
+[Recommended Alarms](#recommended-alarms)).
 
 ## Deploy-time invocation: `.invokeOnDeploy()`
 

package/dist/commonjs/alarm-config.d.ts

@@ -114,7 +114,7 @@ export interface FunctionAlarmConfig {
      * Alarm when the function is falling behind a stream event source.
      *
      * Contextual: a single alarm is created when at least one stream event
-     * source (currently DynamoDB streams) is attached via
+     * source (DynamoDB streams or Kinesis) is attached via
      * {@link IFunctionBuilder.addEventSource}. Unlike the per-mapping
      * {@link FunctionAlarmConfig.eventSourceFailedInvocations} /
      * {@link FunctionAlarmConfig.eventSourceDroppedEvents} alarms, `IteratorAge`

package/dist/commonjs/event-sources/composure-event-source.d.ts

@@ -9,7 +9,7 @@ import type { Resolvable } from "@composurecdk/core";
  * straight to {@link IFunctionBuilder.addEventSource} as an escape hatch —
  * the builder still attaches it, but cannot reason about it.
  */
-export type EventSourceKind = "sqs" | "dynamodb" | "unknown";
+export type EventSourceKind = "sqs" | "dynamodb" | "kinesis" | "unknown";
 /** @internal — brands {@link ComposureEventSource} so the guard is unambiguous. */
 declare const COMPOSURE_EVENT_SOURCE: unique symbol;
 /**
@@ -40,7 +40,7 @@ export declare function composureEventSource(kind: EventSourceKind, source: Reso
 /**
  * Reads the event source mapping UUID off a bound CDK source, keyed by
  * {@link EventSourceKind}. Defined only for kinds whose per-mapping ESM
- * metrics back contextual alarms (SQS and DynamoDB streams); `FunctionBuilder`
+ * metrics back contextual alarms (SQS, DynamoDB and Kinesis streams); `FunctionBuilder`
  * invokes the reader after `addEventSource` so the binding exists. Keying off
  * `kind` — like {@link EVENT_SOURCE_ALARM_SPECS} — keeps the builder from
  * `instanceof`-ing CDK source classes.
@@ -67,7 +67,7 @@ export interface AttachedEventSource {
     kind: EventSourceKind;
     /**
      * The event source mapping UUID, populated for kinds whose per-mapping
-     * ESM metrics back contextual alarms (currently SQS only). The contextual
+     * ESM metrics back contextual alarms (SQS and the stream kinds). The contextual
      * alarms key off this dimension.
      */
     eventSourceMappingId?: string;

package/dist/commonjs/event-sources/composure-event-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composure-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/composure-event-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,UAAU,GAAG,SAAS,CAAC;AAE7D,mFAAmF;AACnF,QAAA,MAAM,sBAAsB,eAAgD,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,gBAAgB;IAChB,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC;IAExC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;CAC3C;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,GAC/B,oBAAoB,CAEtB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAClD,eAAe,EACf,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,GAAG,SAAS,CAW9C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,GAAG,YAAY,GACzC,KAAK,IAAI,oBAAoB,CAE/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IAEZ,8DAA8D;IAC9D,IAAI,EAAE,eAAe,CAAC;IAEtB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B"}
+{"version":3,"file":"composure-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/composure-event-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAO3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAEzE,mFAAmF;AACnF,QAAA,MAAM,sBAAsB,eAAgD,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,gBAAgB;IAChB,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC;IAExC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;CAC3C;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,GAC/B,oBAAoB,CAEtB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAClD,eAAe,EACf,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,GAAG,SAAS,CAgB9C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,GAAG,YAAY,GACzC,KAAK,IAAI,oBAAoB,CAE/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IAEZ,8DAA8D;IAC9D,IAAI,EAAE,eAAe,CAAC;IAEtB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B"}

package/dist/commonjs/event-sources/composure-event-source.js

@@ -12,7 +12,7 @@ function composureEventSource(kind, source) {
 /**
  * Reads the event source mapping UUID off a bound CDK source, keyed by
  * {@link EventSourceKind}. Defined only for kinds whose per-mapping ESM
- * metrics back contextual alarms (SQS and DynamoDB streams); `FunctionBuilder`
+ * metrics back contextual alarms (SQS, DynamoDB and Kinesis streams); `FunctionBuilder`
  * invokes the reader after `addEventSource` so the binding exists. Keying off
  * `kind` — like {@link EVENT_SOURCE_ALARM_SPECS} — keeps the builder from
  * `instanceof`-ing CDK source classes.
@@ -28,6 +28,10 @@ exports.EVENT_SOURCE_MAPPING_ID_READERS = {
     // which constructs the `DynamoEventSource` in the same call — kind and
     // concrete class move in lockstep.
     dynamodb: (bound) => bound.eventSourceMappingId,
+    // Safe: the `"kinesis"` kind is only ever assigned by `kinesisEventSource()`
+    // and `kinesisConsumerEventSource()`, which construct the matching CDK
+    // source in the same call.
+    kinesis: (bound) => bound.eventSourceMappingId,
     unknown: undefined,
 };
 /**

package/dist/commonjs/event-sources/composure-event-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"composure-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/composure-event-source.ts"],"names":[],"mappings":";;;AA6CA,oDAKC;AA+BD,wDAIC;AAtED,mFAAmF;AACnF,MAAM,sBAAsB,GAAG,MAAM,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;AA4B7E,oEAAoE;AACpE,SAAgB,oBAAoB,CAClC,IAAqB,EACrB,MAAgC;IAEhC,OAAO,EAAE,CAAC,sBAAsB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;;;;;GASG;AACU,QAAA,+BAA+B,GAGxC;IACF,4EAA4E;IAC5E,6EAA6E;IAC7E,oBAAoB;IACpB,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,CAAE,KAAwB,CAAC,oBAAoB;IAC9D,8EAA8E;IAC9E,uEAAuE;IACvE,mCAAmC;IACnC,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAE,KAA2B,CAAC,oBAAoB;IACtE,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF;;;GAGG;AACH,SAAgB,sBAAsB,CACpC,KAA0C;IAE1C,OAAO,sBAAsB,IAAI,KAAK,CAAC;AACzC,CAAC"}
+{"version":3,"file":"composure-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/composure-event-source.ts"],"names":[],"mappings":";;;AAkDA,oDAKC;AAoCD,wDAIC;AA3ED,mFAAmF;AACnF,MAAM,sBAAsB,GAAG,MAAM,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;AA4B7E,oEAAoE;AACpE,SAAgB,oBAAoB,CAClC,IAAqB,EACrB,MAAgC;IAEhC,OAAO,EAAE,CAAC,sBAAsB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;;;;;GASG;AACU,QAAA,+BAA+B,GAGxC;IACF,4EAA4E;IAC5E,6EAA6E;IAC7E,oBAAoB;IACpB,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,CAAE,KAAwB,CAAC,oBAAoB;IAC9D,8EAA8E;IAC9E,uEAAuE;IACvE,mCAAmC;IACnC,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAE,KAA2B,CAAC,oBAAoB;IACtE,6EAA6E;IAC7E,uEAAuE;IACvE,2BAA2B;IAC3B,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAChB,KAAyD,CAAC,oBAAoB;IACjF,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF;;;GAGG;AACH,SAAgB,sBAAsB,CACpC,KAA0C;IAE1C,OAAO,sBAAsB,IAAI,KAAK,CAAC;AACzC,CAAC"}

package/dist/commonjs/event-sources/dynamodb-event-source.d.ts

@@ -2,8 +2,8 @@ import type { ITable } from "aws-cdk-lib/aws-dynamodb";
 import type { StartingPosition } from "aws-cdk-lib/aws-lambda";
 import { type DynamoEventSourceProps } from "aws-cdk-lib/aws-lambda-event-sources";
 import type { IQueue } from "aws-cdk-lib/aws-sqs";
-import { type Resolvable } from "@composurecdk/core";
-import { type ComposureEventSource } from "./composure-event-source.js";
+import type { Resolvable } from "@composurecdk/core";
+import type { ComposureEventSource } from "./composure-event-source.js";
 /**
  * Secure, AWS-recommended defaults applied to every DynamoDB stream event
  * source built with {@link dynamoEventSource} — the shared

package/dist/commonjs/event-sources/dynamodb-event-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamodb-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/dynamodb-event-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAgB,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAEL,KAAK,sBAAsB,EAE5B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,KAAK,oBAAoB,EAAwB,MAAM,6BAA6B,CAAC;AAG9F;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,sKAAoC,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,WAAW,4BAA6B,SAAQ,IAAI,CACxD,sBAAsB,EACtB,WAAW,GAAG,kBAAkB,CACjC;IACC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,UAAU,CAAC,MAAM,GAAG,WAAW,CAAC,sBAAsB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;CACnF;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,KAAK,CAAC,EAAE,4BAA4B,GACnC,oBAAoB,CAwBtB"}
+{"version":3,"file":"dynamodb-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/dynamodb-event-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAIxE;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,sKAAoC,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,WAAW,4BAA6B,SAAQ,IAAI,CACxD,sBAAsB,EACtB,WAAW,GAAG,kBAAkB,CACjC;IACC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,UAAU,CAAC,MAAM,GAAG,WAAW,CAAC,sBAAsB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;CACnF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,KAAK,CAAC,EAAE,4BAA4B,GACnC,oBAAoB,CAOtB"}

package/dist/commonjs/event-sources/dynamodb-event-source.js

@@ -3,8 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_DYNAMO_EVENT_SOURCE_PROPS = void 0;
 exports.dynamoEventSource = dynamoEventSource;
 const aws_lambda_event_sources_1 = require("aws-cdk-lib/aws-lambda-event-sources");
-const core_1 = require("@composurecdk/core");
-const composure_event_source_js_1 = require("./composure-event-source.js");
+const stream_event_source_js_1 = require("./stream-event-source.js");
 const stream_event_source_defaults_js_1 = require("./stream-event-source-defaults.js");
 /**
  * Secure, AWS-recommended defaults applied to every DynamoDB stream event
@@ -14,12 +13,6 @@ const stream_event_source_defaults_js_1 = require("./stream-event-source-default
  * property can be overridden via the factory's `props` argument.
  */
 exports.DEFAULT_DYNAMO_EVENT_SOURCE_PROPS = stream_event_source_defaults_js_1.DEFAULT_STREAM_EVENT_SOURCE_PROPS;
-/** Wraps a raw queue in an {@link SqsDlq}; passes an existing destination through. */
-function toDlq(destination) {
-    // Duck-type the queue rather than `instanceof` — the ESM and CommonJS copies
-    // of a package can both load in one process (ADR-0007).
-    return "queueArn" in destination ? new aws_lambda_event_sources_1.SqsDlq(destination) : destination;
-}
 /**
  * Wraps a DynamoDB table's change stream as a Lambda {@link IEventSource},
  * deferring resolution when the table (or the `onFailure` DLQ) is a `ref()` to
@@ -80,23 +73,6 @@ function toDlq(destination) {
  * ```
  */
 function dynamoEventSource(table, props) {
-    const { onFailure, ...rest } = props ?? {};
-    const merged = {
-        ...exports.DEFAULT_DYNAMO_EVENT_SOURCE_PROPS,
-        ...rest,
-    };
-    let source;
-    if (onFailure === undefined) {
-        // No DLQ: only the table can be lazy — preserve the single-ref fast path.
-        source = (0, core_1.isRef)(table)
-            ? table.map((resolved) => new aws_lambda_event_sources_1.DynamoEventSource(resolved, merged))
-            : new aws_lambda_event_sources_1.DynamoEventSource(table, merged);
-    }
-    else {
-        // Table and DLQ are two siblings feeding one source — combine both refs
-        // (either may be concrete) into a single deferred value (ADR-0015).
-        source = (0, core_1.combine)({ table, onFailure }, ({ table: resolvedTable, onFailure: resolvedDlq }) => new aws_lambda_event_sources_1.DynamoEventSource(resolvedTable, { ...merged, onFailure: toDlq(resolvedDlq) }));
-    }
-    return (0, composure_event_source_js_1.composureEventSource)("dynamodb", source);
+    return (0, stream_event_source_js_1.streamEventSource)("dynamodb", table, props, (resolved, merged) => new aws_lambda_event_sources_1.DynamoEventSource(resolved, merged));
 }
 //# sourceMappingURL=dynamodb-event-source.js.map

package/dist/commonjs/event-sources/dynamodb-event-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"dynamodb-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/dynamodb-event-source.ts"],"names":[],"mappings":";;;AA4HA,8CA2BC;AArJD,mFAI8C;AAE9C,6CAAqE;AACrE,2EAA8F;AAC9F,uFAAsF;AAEtF;;;;;;GAMG;AACU,QAAA,iCAAiC,GAAG,mEAAiC,CAAC;AAqCnF,sFAAsF;AACtF,SAAS,KAAK,CACZ,WAAsE;IAEtE,6EAA6E;IAC7E,wDAAwD;IACxD,OAAO,UAAU,IAAI,WAAW,CAAC,CAAC,CAAC,IAAI,iCAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,SAAgB,iBAAiB,CAC/B,KAAyB,EACzB,KAAoC;IAEpC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,IAAI,EAAE,CAAC;IAC3C,MAAM,MAAM,GAA8C;QACxD,GAAG,yCAAiC;QACpC,GAAG,IAAI;KACR,CAAC;IAEF,IAAI,MAAgC,CAAC;IACrC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,0EAA0E;QAC1E,MAAM,GAAG,IAAA,YAAK,EAAC,KAAK,CAAC;YACnB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,4CAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAClE,CAAC,CAAC,IAAI,4CAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;SAAM,CAAC;QACN,wEAAwE;QACxE,oEAAoE;QACpE,MAAM,GAAG,IAAA,cAAO,EACd,EAAE,KAAK,EAAE,SAAS,EAAE,EACpB,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,EAAE,EAAE,CACnD,IAAI,4CAAiB,CAAC,aAAa,EAAE,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CACrF,CAAC;IACJ,CAAC;IAED,OAAO,IAAA,gDAAoB,EAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC"}
+{"version":3,"file":"dynamodb-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/dynamodb-event-source.ts"],"names":[],"mappings":";;;AAmHA,8CAUC;AA3HD,mFAG8C;AAI9C,qEAA6D;AAC7D,uFAAsF;AAEtF;;;;;;GAMG;AACU,QAAA,iCAAiC,GAAG,mEAAiC,CAAC;AAqCnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,SAAgB,iBAAiB,CAC/B,KAAyB,EACzB,KAAoC;IAEpC,OAAO,IAAA,0CAAiB,EACtB,UAAU,EACV,KAAK,EACL,KAAK,EACL,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,4CAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAC9D,CAAC;AACJ,CAAC"}

package/dist/commonjs/event-sources/event-source-relationship-guards.d.ts

@@ -26,8 +26,9 @@ export type EventSourceRelationshipGuard = (fn: LambdaFunction, id: string, key:
 /**
  * Per-kind relationship guards, keyed by {@link EventSourceKind}. A kind maps to
  * the (possibly empty) list of relationships to guard for a source of that kind
- * — SQS gains a second entry for the `maxReceiveCount` floor (#124), and a bare
- * escape-hatch source attached as `"unknown"` has none.
+ * — a bare escape-hatch source attached as `"unknown"` has none. The SQS
+ * `maxReceiveCount` floor is not a relationship guard: it concerns the queue
+ * alone, so `@composurecdk/sqs`'s `QueueBuilder` checks it.
  *
  * @internal
  */

package/dist/commonjs/event-sources/event-source-relationship-guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-source-relationship-guards.d.ts","sourceRoot":"","sources":["../../../src/event-sources/event-source-relationship-guards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqC,KAAK,QAAQ,EAAS,MAAM,aAAa,CAAC;AACtF,OAAO,EAEL,KAAK,QAAQ,IAAI,cAAc,EAC/B,KAAK,YAAY,EAClB,MAAM,wBAAwB,CAAC;AAIhC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAiBnE;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,gDAAgD,CAAC;AAE/F;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,4CAA4C,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,MAAM,4BAA4B,GAAG,CACzC,EAAE,EAAE,cAAc,EAClB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,QAAQ,GAAG,SAAS,KAC1B,IAAI,CAAC;AAEV;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,EAAE,MAAM,CACnD,eAAe,EACf,4BAA4B,EAAE,CAO/B,CAAC"}
+{"version":3,"file":"event-source-relationship-guards.d.ts","sourceRoot":"","sources":["../../../src/event-sources/event-source-relationship-guards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqC,KAAK,QAAQ,EAAS,MAAM,aAAa,CAAC;AACtF,OAAO,EAEL,KAAK,QAAQ,IAAI,cAAc,EAC/B,KAAK,YAAY,EAClB,MAAM,wBAAwB,CAAC;AAIhC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAiBnE;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,gDAAgD,CAAC;AAE/F;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,4CAA4C,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,MAAM,4BAA4B,GAAG,CACzC,EAAE,EAAE,cAAc,EAClB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,QAAQ,GAAG,SAAS,KAC1B,IAAI,CAAC;AAEV;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,EAAE,MAAM,CACnD,eAAe,EACf,4BAA4B,EAAE,CAQ/B,CAAC"}

package/dist/commonjs/event-sources/event-source-relationship-guards.js

@@ -33,16 +33,18 @@ exports.STREAM_DLQ_WARNING_ID = "@composurecdk/lambda:stream-dlq-missing";
 /**
  * Per-kind relationship guards, keyed by {@link EventSourceKind}. A kind maps to
  * the (possibly empty) list of relationships to guard for a source of that kind
- * — SQS gains a second entry for the `maxReceiveCount` floor (#124), and a bare
- * escape-hatch source attached as `"unknown"` has none.
+ * — a bare escape-hatch source attached as `"unknown"` has none. The SQS
+ * `maxReceiveCount` floor is not a relationship guard: it concerns the queue
+ * alone, so `@composurecdk/sqs`'s `QueueBuilder` checks it.
  *
  * @internal
  */
 exports.EVENT_SOURCE_RELATIONSHIP_GUARDS = {
     sqs: [guardSqsVisibilityTimeout],
     // `guardStreamFailureDestination` is source-agnostic — it reads only the
-    // mapping's own failure config — so a future `kinesis` kind reuses it as-is.
+    // mapping's own failure config — so every stream kind shares it.
     dynamodb: [guardStreamFailureDestination],
+    kinesis: [guardStreamFailureDestination],
     unknown: [],
 };
 /**
@@ -124,7 +126,7 @@ function isFiniteBound(value) {
  * source does not re-expose them), regardless of build order (ADR-0011).
  *
  * Source-agnostic: it inspects only the mapping's own failure config, so it
- * applies unchanged to any polling stream kind (DynamoDB now, Kinesis later).
+ * applies unchanged to every polling stream kind (DynamoDB and Kinesis).
  * SQS mappings never set these stream-only properties, so the guard stays
  * silent even though the Aspect visits them.
  */
@@ -149,7 +151,9 @@ function guardStreamFailureDestination(fn, id) {
                 `retries/record-age but has no onFailure destination — records that exhaust the bound ` +
                 `are dropped silently. Set onFailure to a dead-letter queue (e.g. the sqs "dlq" queue ` +
                 `builder) or acknowledge "${exports.STREAM_DLQ_WARNING_ID}". ` +
-                `See https://docs.aws.amazon.com/lambda/latest/dg/with-ddb.html#services-ddb-errors`);
+                `See https://docs.aws.amazon.com/lambda/latest/dg/with-ddb.html#services-ddb-errors ` +
+                `(DynamoDB) or https://docs.aws.amazon.com/lambda/latest/dg/kinesis-on-failure-destination.html ` +
+                `(Kinesis)`);
         },
     });
 }

package/dist/commonjs/event-sources/event-source-relationship-guards.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-source-relationship-guards.js","sourceRoot":"","sources":["../../../src/event-sources/event-source-relationship-guards.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"event-source-relationship-guards.js","sourceRoot":"","sources":["../../../src/event-sources/event-source-relationship-guards.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/event-sources/kinesis-event-source.d.ts

@@ -0,0 +1,129 @@
+import type { IStream, IStreamConsumer } from "aws-cdk-lib/aws-kinesis";
+import type { StartingPosition } from "aws-cdk-lib/aws-lambda";
+import { type KinesisEventSourceProps } from "aws-cdk-lib/aws-lambda-event-sources";
+import type { IQueue } from "aws-cdk-lib/aws-sqs";
+import type { Resolvable } from "@composurecdk/core";
+import type { ComposureEventSource } from "./composure-event-source.js";
+/**
+ * Secure, AWS-recommended defaults applied to every Kinesis event source built
+ * with {@link kinesisEventSource} or {@link kinesisConsumerEventSource} — the
+ * shared {@link DEFAULT_STREAM_EVENT_SOURCE_PROPS} (start at the stream tip,
+ * report partial batch failures, bisect a failing batch, emit ESM metrics).
+ * Each property can be overridden via the factory's `props` argument.
+ *
+ * @see https://docs.aws.amazon.com/lambda/latest/dg/services-kinesis-parameters.html
+ */
+export declare const DEFAULT_KINESIS_EVENT_SOURCE_PROPS: Pick<import("aws-cdk-lib/aws-lambda-event-sources").StreamEventSourceProps, "reportBatchItemFailures" | "metricsConfig" | "startingPosition" | "bisectBatchOnError">;
+/**
+ * Props for {@link kinesisEventSource} and {@link kinesisConsumerEventSource}.
+ * Identical to CDK's {@link KinesisEventSourceProps} except that
+ * `startingPosition` is optional and `onFailure` is widened to a
+ * {@link Resolvable} that additionally accepts a bare {@link IQueue} (or a
+ * `ref()` to one), wrapped in an `SqsDlq` for you — so a dead-letter queue
+ * built by a sibling component wires up declaratively:
+ * `onFailure: ref("dlq", (r) => r.queue)`.
+ */
+export interface KinesisStreamEventSourceProps extends Omit<KinesisEventSourceProps, "onFailure" | "startingPosition"> {
+    /**
+     * Where to start reading the stream. Optional here — unlike CDK's
+     * {@link KinesisEventSourceProps} — because
+     * {@link DEFAULT_KINESIS_EVENT_SOURCE_PROPS} supplies
+     * {@link StartingPosition.LATEST} when omitted. `AT_TIMESTAMP` also needs
+     * `startingPositionTimestamp`.
+     */
+    startingPosition?: StartingPosition;
+    /**
+     * Destination for records that exhaust `retryAttempts` or exceed
+     * `maxRecordAge`. Pass an {@link IQueue} (wrapped in an `SqsDlq`
+     * automatically), a concrete destination, or a `ref()` to a sibling that
+     * produces either.
+     *
+     * The destination arm is read from CDK's own prop rather than named as
+     * `IEventSourceDlq`, so it keeps tracking that type as CDK moves it
+     * (ADR-0018). The `IQueue` arm is the builder's own convenience and has no
+     * CDK prop to read from.
+     *
+     * @see https://docs.aws.amazon.com/lambda/latest/dg/kinesis-on-failure-destination.html
+     */
+    onFailure?: Resolvable<IQueue | NonNullable<KinesisEventSourceProps["onFailure"]>>;
+}
+/**
+ * Wraps a Kinesis data stream as a Lambda {@link IEventSource} using
+ * **shared-throughput** (standard) iterators, deferring resolution when the
+ * stream (or the `onFailure` destination) is a `ref()` to a sibling
+ * component's output.
+ *
+ * Register the result with {@link IFunctionBuilder.addEventSource}: the
+ * builder resolves the `ref()`, attaches the source, and (because
+ * `addEventSource` calls `source.bind(fn)`) grants the function's
+ * least-privilege execution role permission to read the stream — including
+ * `kms:Decrypt` when the stream is encrypted with a customer-managed key.
+ *
+ * Applies {@link DEFAULT_KINESIS_EVENT_SOURCE_PROPS}; pass `props` to override.
+ * For a dedicated 2 MB/s-per-shard read pipe instead of sharing the shard's
+ * read throughput with other consumers, use {@link kinesisConsumerEventSource}.
+ *
+ * ## Failure handling (AWS Well-Architected)
+ *
+ * By default Lambda retries a failing batch until its records expire from the
+ * stream, blocking the shard for up to the stream's retention period (24 h by
+ * CDK's default, 7 days with `@composurecdk/kinesis`). `bisectBatchOnError` is
+ * on by default to isolate a poison record; for durable failure handling also
+ * bound `retryAttempts` / `maxRecordAge` **and** set `onFailure` so exhausted
+ * records land in a dead-letter destination instead of being dropped —
+ * bounding retries without one triggers a suppressible synth-time warning (see
+ * {@link STREAM_DLQ_WARNING_ID}).
+ *
+ * @see https://docs.aws.amazon.com/lambda/latest/dg/services-kinesis-parameters.html
+ * @see https://docs.aws.amazon.com/lambda/latest/dg/services-kinesis-batchfailurereporting.html
+ *
+ * @param stream - The source stream, concrete or a `ref()` to a sibling.
+ * @param props - Overrides for {@link DEFAULT_KINESIS_EVENT_SOURCE_PROPS} and
+ *   any other {@link KinesisStreamEventSourceProps}.
+ *
+ * @example
+ * ```ts
+ * compose(
+ *   {
+ *     telemetry: createStreamBuilder(),
+ *     dlq: createQueueBuilder("dlq"),
+ *     processor: createFunctionBuilder()
+ *       .runtime(Runtime.NODEJS_22_X)
+ *       .handler("index.handler")
+ *       .code(Code.fromAsset("lambda"))
+ *       .addEventSource(
+ *         "telemetry",
+ *         kinesisEventSource(ref("telemetry", (r) => r.stream), {
+ *           retryAttempts: 3,
+ *           onFailure: ref("dlq", (r) => r.queue),
+ *         }),
+ *       ),
+ *   },
+ *   { telemetry: [], dlq: [], processor: ["telemetry", "dlq"] },
+ * );
+ * ```
+ */
+export declare function kinesisEventSource(stream: Resolvable<IStream>, props?: KinesisStreamEventSourceProps): ComposureEventSource;
+/**
+ * Wraps a Kinesis **enhanced fan-out** consumer as a Lambda
+ * {@link IEventSource}. Same defaults, `onFailure` handling and `ref()`
+ * resolution as {@link kinesisEventSource}; the function reads through the
+ * registered consumer, which gets its own 2 MB/s per shard of read
+ * throughput pushed over HTTP/2 rather than sharing the shard's 2 MB/s with
+ * every other polling consumer.
+ *
+ * Use it when several applications read the same stream, or when the
+ * function needs the lowest propagation delay; enhanced fan-out is billed
+ * per consumer-shard-hour and per GB retrieved, so a single consumer is
+ * usually cheaper on shared throughput.
+ *
+ * @see https://docs.aws.amazon.com/streams/latest/dev/enhanced-consumers.html
+ * @see https://docs.aws.amazon.com/lambda/latest/dg/services-kinesis-parameters.html
+ *
+ * @param consumer - The registered stream consumer, concrete or a `ref()` to
+ *   a sibling.
+ * @param props - Overrides for {@link DEFAULT_KINESIS_EVENT_SOURCE_PROPS} and
+ *   any other {@link KinesisStreamEventSourceProps}.
+ */
+export declare function kinesisConsumerEventSource(consumer: Resolvable<IStreamConsumer>, props?: KinesisStreamEventSourceProps): ComposureEventSource;
+//# sourceMappingURL=kinesis-event-source.d.ts.map

package/dist/commonjs/event-sources/kinesis-event-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinesis-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/kinesis-event-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAIxE;;;;;;;;GAQG;AACH,eAAO,MAAM,kCAAkC,sKAAoC,CAAC;AAEpF;;;;;;;;GAQG;AACH,MAAM,WAAW,6BAA8B,SAAQ,IAAI,CACzD,uBAAuB,EACvB,WAAW,GAAG,kBAAkB,CACjC;IACC;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,UAAU,CAAC,MAAM,GAAG,WAAW,CAAC,uBAAuB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;CACpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,EAC3B,KAAK,CAAC,EAAE,6BAA6B,GACpC,oBAAoB,CAOtB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,UAAU,CAAC,eAAe,CAAC,EACrC,KAAK,CAAC,EAAE,6BAA6B,GACpC,oBAAoB,CAOtB"}