fix(parser): API Gateway Envelopes handle non-JSON

[dreamorosi]

Summary

Changes

Please provide a summary of what's being changed

This PR refactors the API Gateway (REST) & API Gateway v2 (HTTP) envelopes so that they don't force the transform of the body field and thus can handle plain text and base64 binary-encoded bodies.

The body is now left as a string and it's up to the caller to set the appropriate transform in the Zod schema passed to the envelope, for example to

import { z } from 'zod';
import { JSONStringified } from '@aws-lambda-powertools/parser/helpers';

const schema = z.object({
  message: z.string()
});

ApiGatewayEnvelope.parse(event, JSONStringified(schema));

If there's demand for it, in the future we can consider adding an helper for base64 decoding.

Additionally I standardized the error structure by always throwing a ParseError with the original error as cause:

new ParseError('Failed to parse API Gateway body', {
  cause: new ZodError([
    {
      code: 'invalid_type',
      expected: 'string',
      received: 'undefined',
      path: ['path'],
      message: 'Required',
    },
    {
      code: 'invalid_type',
      expected: 'object',
      received: 'null',
      path: ['body'],
      message: 'Expected object, received null',
    },
  ]),
})

Please add the issue number below, if no issue is present the PR might get blocked and not be reviewed

Issue number: closes #3512

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
3.0% Duplication on New Code

See analysis details on SonarQube Cloud

[am29d]

Thanks for PR, and making the tests more explicit with ParseErrors.