feat(parameters): add support for AppConfig Agent

[svozza]

Summary

Adds a new getConfig function exported from @aws-lambda-powertools/parameters/appconfig-agent that retrieves configurations from the AWS AppConfig Agent Lambda extension's local HTTP endpoint. Since caching, polling, and prefetching are handled by the agent, the implementation is a lean standalone function modeled on the commons metadata module rather than the BaseProvider pattern, keeping customer bundles small.

Changes

• Add getConfig function in packages/parameters/src/appconfig-agent/ that fetches from http://localhost:2772/applications/{app}/environments/{env}/configurations/{config} using native fetch with a configurable timeout (default 3000ms)
• Support json and binary transforms by reusing the existing transformValue utility; no maxAge/forceFetch options since caching is handled by the agent
• Return undefined when not running in a Lambda environment (local development/testing)
• Respect the AWS_APPCONFIG_EXTENSION_HTTP_PORT environment variable and fall back to POWERTOOLS_SERVICE_NAME when application is not provided
• Add ./appconfig-agent and ./appconfig-agent/types subpath exports with typed return values (string, JSONValue, or explicit generic)
• Add unit tests (100% coverage), type tests, and an e2e test suite that deploys the agent extension layer alongside AppConfig profiles
• Document the new function in the Parameters feature page, README, and add a doc snippet

Issue number: closes #5312

---

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.

[svozza]

E2E tests pass: https://github.com/aws-powertools/powertools-lambda-typescript/actions/runs/28928374948

[svozza]

Note: we always throw if a parameter is not found. If we want to do something different and say return undefined, then we need to revisit the behaviour when we are not running in a lambda because currently that is what undefined means.

The issue here is I can't think of a different way to represent not running in a lambda other than throwing: we can't do what we do in metdata by just returning an empty object because that is a valid return value for a parameter.

Open to suggestions here: maybe allowing users to supply a default value that means they can avoid this ParameterNotFoundError error. There is also the issue that we are missing the throwOnMissing behaviour that other parameter types have, which could confuse users.

[dreamorosi]

This for me is the biggest one-way door / question mark to be honest.

On one hand, I understand why we're throwing based on your explanation above, but on the other hand I don't think it's in line with the rest of the library and that's a minus - which you also have pointed out.

What do you think about not throwing unless throwOnMissing is present and also returning a clearly fake object like:

{
  "testing": true
}

or something like this - which would have to properly document.

Conversely, what would it take for us to allow customers to specify what to return? Would having something like POWERTOOLS_APPCONFIG_AGENT_RETURN_VALUE="{\"foo\": true}" be an option?

[svozza]

Went with a combination of both of your suggestions, implemented in 113fc08:

1. 404 now returns undefined by default, in line with the rest of the library (DynamoDB/AppConfig provider semantics). This also means users get per-call fallback values for free via nullish coalescing — await getConfig(...) ?? DEFAULT_FLAGS — which we think covers the 'return a specific value when not found' use case with full type safety and no new API.
2. throwOnMissing: true opts into ParameterNotFoundError, same flag and semantics as the provider-based functions, including the GetMaybeUndefined return-type narrowing.
3. POWERTOOLS_APPCONFIG_AGENT_RETURN_VALUE for the not-in-Lambda case: rather than a hardcoded fake object (which would be a type lie for the no-transform/binary cases and a dangerously plausible {} for json), the env var value is treated as the agent response body and runs through the normal transform pipeline. Users pick a shape-correct value for their config; unset means undefined as before. Documented in a new 'Testing getConfig' section with a snippet.

On the fake-object idea specifically: anything the library invents can't satisfy the string return branches, and for json an empty-ish object reads as 'all flags off' with no failure signal — the env var sidesteps both since the customer supplies the value.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud