add drop example

Author: roger-zhangg

docs/utilities/data_classes.md

@@ -989,10 +989,6 @@ in the example below.
     ```python
     --8<-- "examples/event_sources/src/kinesis_firehose_delivery_stream.py"
     ```
-=== "with Failure"
-    ```python hl_lines="25"
-    --8<-- "examples/event_sources/src/kinesis_firehose_delivery_stream_failed.py"
-    ```
 
 You can also construct response without using `event_source` wrapper. Shown in the example below.
 
@@ -1001,10 +997,14 @@ You can also construct response without using `event_source` wrapper. Shown in t
     ```python
     --8<-- "examples/event_sources/src/kinesis_firehose_response.py"
     ```
-=== "with Exception"
-    ```python hl_lines="26"
+=== "with Failure"
+    ```python hl_lines="30"
     --8<-- "examples/event_sources/src/kinesis_firehose_response_exception.py"
     ```
+=== "with Dropped"
+    ```python hl_lines="30"
+    --8<-- "examples/event_sources/src/kinesis_firehose_response_drop.py"
+    ```
 
 ### Lambda Function URL
 

examples/event_sources/src/kinesis_firehose_delivery_stream_failed.py

@@ -1,27 +1,27 @@
-import base64
-
 from aws_lambda_powertools.utilities.data_classes import (
     KinesisFirehoseDataTransformationRecord,
     KinesisFirehoseDataTransformationResponse,
+    KinesisFirehoseEvent,
 )
 from aws_lambda_powertools.utilities.serialization import base64_from_json
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
 
 def lambda_handler(event: dict, context: LambdaContext):
+    firehose_event = KinesisFirehoseEvent(event)
     result = KinesisFirehoseDataTransformationResponse()
 
-    for record in event["records"]:
-        print(record["recordId"])
-        payload = base64.b64decode(record["data"]).decode("utf-8")
-        ## do all kind of stuff with payload
+    for record in firehose_event.records:
+        payload = record.data_as_text  # base64 decoded data as str
+
         ## generate data to return
         transformed_data = {"tool_used": "powertools_dataclass", "original_payload": payload}
 
         processed_record = KinesisFirehoseDataTransformationRecord(
-            record_id=record["recordId"],
+            record_id=record.record_id,
             data=base64_from_json(transformed_data),
         )
+
         result.add_record(processed_record)
 
     # return transformed records

examples/event_sources/src/kinesis_firehose_response.py

@@ -0,0 +1,36 @@
+from aws_lambda_powertools.utilities.data_classes import (
+    KinesisFirehoseDataTransformationRecord,
+    KinesisFirehoseDataTransformationResponse,
+    KinesisFirehoseEvent,
+)
+from aws_lambda_powertools.utilities.serialization import base64_from_json
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    firehose_event = KinesisFirehoseEvent(event)
+    result = KinesisFirehoseDataTransformationResponse()
+
+    for record in firehose_event.records:
+        try:
+            payload = record.data_as_text  # base64 decoded data as str
+            ## do all kind of stuff with payload
+            ## generate data to return
+            transformed_data = {"tool_used": "powertools_dataclass", "original_payload": payload}
+            # Default result is Ok
+            processed_record = KinesisFirehoseDataTransformationRecord(
+                record_id=record.record_id,
+                data=base64_from_json(transformed_data),
+            )
+        except Exception:
+            # encountered failure that couldn't be fixed by retry
+            processed_record = KinesisFirehoseDataTransformationRecord(
+                record_id=record.record_id,
+                data=record.data,
+                result="Dropped",
+            )
+
+        result.add_record(processed_record)
+
+    # return transformed records
+    return result.asdict()

examples/event_sources/src/kinesis_firehose_response_drop.py

@@ -1,38 +1,35 @@
-import base64
-
 from aws_lambda_powertools.utilities.data_classes import (
     KinesisFirehoseDataTransformationRecord,
     KinesisFirehoseDataTransformationResponse,
+    KinesisFirehoseEvent,
 )
 from aws_lambda_powertools.utilities.serialization import base64_from_json
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
 
 def lambda_handler(event: dict, context: LambdaContext):
+    firehose_event = KinesisFirehoseEvent(event)
     result = KinesisFirehoseDataTransformationResponse()
 
-    for record in event["records"]:
-        print(record["recordId"])
+    for record in firehose_event.records:
         try:
-            payload = base64.b64decode(record["data"]).decode("utf-8")
+            payload = record.data_as_text  # base64 decoded data as str
             ## do all kind of stuff with payload
             ## generate data to return
             transformed_data = {"tool_used": "powertools_dataclass", "original_payload": payload}
-        except Exception:
-            # add Failed result to processing results and send back to kinesis
+            # Default result is Ok
             processed_record = KinesisFirehoseDataTransformationRecord(
-                record_id=record["recordId"],
+                record_id=record.record_id,
                 data=base64_from_json(transformed_data),
+            )
+        except Exception:
+            # add Failed result to processing results, send back to kinesis for retry
+            processed_record = KinesisFirehoseDataTransformationRecord(
+                record_id=record.record_id,
+                data=record.data,
                 result="ProcessingFailed",
             )
-            result.add_record(processed_record)
-            continue
 
-        # Default result is Ok
-        processed_record = KinesisFirehoseDataTransformationRecord(
-            record_id=record["recordId"],
-            data=base64_from_json(transformed_data),
-        )
         result.add_record(processed_record)
 
     # return transformed records