feat(sdk): validate durable execution input payload (#334)

Add validation to ensure Lambda functions wrapped with
withDurableExecution receive proper durable execution payloads. Throws
clear error message when DurableExecutionArn or CheckpointToken are
missing, preventing confusing downstream errors.

- Add validateDurableExecutionEvent function in
with-durable-execution.ts
- Add unit tests for invalid payload scenarios
- Use unknown type instead of any for better type safety

Author: ParidelPooya

packages/aws-durable-execution-sdk-js/src/with-durable-execution.test.ts

@@ -481,4 +481,35 @@ describe("withDurableExecution", () => {
       Result: JSON.stringify(mockResult),
     });
   });
+
+  it("should throw error for invalid durable execution event", async () => {
+    const mockHandler = jest.fn();
+    const wrappedHandler = withDurableExecution(mockHandler);
+
+    // Test missing DurableExecutionArn
+    const invalidEvent1 = { CheckpointToken: "token" };
+    await expect(
+      wrappedHandler(invalidEvent1 as any, mockContext),
+    ).rejects.toThrow(
+      "Unexpected payload provided to start the durable execution",
+    );
+
+    // Test missing CheckpointToken
+    const invalidEvent2 = { DurableExecutionArn: "arn" };
+    await expect(
+      wrappedHandler(invalidEvent2 as any, mockContext),
+    ).rejects.toThrow(
+      "Unexpected payload provided to start the durable execution",
+    );
+
+    // Test completely invalid event
+    const invalidEvent3 = {};
+    await expect(
+      wrappedHandler(invalidEvent3 as any, mockContext),
+    ).rejects.toThrow(
+      "Unexpected payload provided to start the durable execution",
+    );
+
+    expect(mockHandler).not.toHaveBeenCalled();
+  });
 });

packages/aws-durable-execution-sdk-js/src/with-durable-execution.ts

@@ -231,6 +231,22 @@ async function runHandler<
   }
 }
 
+/**
+ * Validates that the event is a proper durable execution input
+ */
+function validateDurableExecutionEvent(event: unknown): void {
+  try {
+    const eventObj = event as Record<string, unknown>;
+    if (!eventObj?.DurableExecutionArn || !eventObj?.CheckpointToken) {
+      throw new Error("Missing required durable execution fields");
+    }
+  } catch {
+    const msg = `Unexpected payload provided to start the durable execution. 
+Check your resource configurations to confirm the durability is set.`;
+    throw new Error(msg);
+  }
+}
+
 export const withDurableExecution = <
   Input,
   Output,
@@ -242,6 +258,7 @@ export const withDurableExecution = <
     event: DurableExecutionInvocationInput,
     context: Context,
   ): Promise<DurableExecutionInvocationOutput> => {
+    validateDurableExecutionEvent(event);
     const { executionContext, durableExecutionMode, checkpointToken } =
       await initializeExecutionContext(event, context);
     let response: DurableExecutionInvocationOutput | null = null;