remove Ok in example response,add failure example

Author: roger-zhangg

docs/utilities/data_classes.md

@@ -989,6 +989,10 @@ 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.
 
@@ -997,6 +1001,10 @@ 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"
+    --8<-- "examples/event_sources/src/kinesis_firehose_response_exception.py"
+    ```
 
 ### Lambda Function URL
 

examples/event_sources/src/kinesis_firehose_delivery_stream.py

@@ -20,7 +20,6 @@ def lambda_handler(event: KinesisFirehoseEvent, context: LambdaContext):
         transformed_data = {"new_data": "transformed data using Powertools", "original_payload": data}
 
         processed_record = record.build_data_transformation_response(
-            result="Ok",
             data=base64_from_json(transformed_data),
         )
 

examples/event_sources/src/kinesis_firehose_delivery_stream_failed.py

@@ -0,0 +1,31 @@
+from aws_lambda_powertools.utilities.data_classes import (
+    KinesisFirehoseDataTransformationResponse,
+    KinesisFirehoseEvent,
+    event_source,
+)
+from aws_lambda_powertools.utilities.serialization import base64_from_json
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+
+@event_source(data_class=KinesisFirehoseEvent)
+def lambda_handler(event: KinesisFirehoseEvent, context: LambdaContext):
+    result = KinesisFirehoseDataTransformationResponse()
+
+    for record in event.records:
+        # get original data using data_as_text property
+        data = record.data_as_text
+
+        ## do all kind of stuff with data
+        ## generate data to return
+        transformed_data = {"new_data": "transformed data using Powertools", "original_payload": data}
+
+        # some process failed, send back to kinesis
+        processed_record = record.build_data_transformation_response(
+            data=base64_from_json(transformed_data),
+            result="ProcessingFailed",
+        )
+
+        result.add_record(processed_record)
+
+    # return transformed records
+    return result.asdict()

examples/event_sources/src/kinesis_firehose_response.py

@@ -20,7 +20,6 @@ def lambda_handler(event: dict, context: LambdaContext):
 
         processed_record = KinesisFirehoseDataTransformationRecord(
             record_id=record["recordId"],
-            result="Ok",
             data=base64_from_json(transformed_data),
         )
         result.add_record(processed_record)

examples/event_sources/src/kinesis_firehose_response_exception.py

@@ -0,0 +1,39 @@
+import base64
+
+from aws_lambda_powertools.utilities.data_classes import (
+    KinesisFirehoseDataTransformationRecord,
+    KinesisFirehoseDataTransformationResponse,
+)
+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):
+    result = KinesisFirehoseDataTransformationResponse()
+
+    for record in event["records"]:
+        print(record["recordId"])
+        try:
+            payload = base64.b64decode(record["data"]).decode("utf-8")
+            ## 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
+            processed_record = KinesisFirehoseDataTransformationRecord(
+                record_id=record["recordId"],
+                data=base64_from_json(transformed_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
+    return result.asdict()