refactor(parameters): improve typing for get_secret method (#3910)

fix: add overloads for get_secret function Co-authored-by: Leandro Damascena <lcdama@amazon.pt>

Author: TonySherman

aws_lambda_powertools/utilities/parameters/secrets.py

@@ -3,11 +3,13 @@
 """
 
 import os
-from typing import TYPE_CHECKING, Any, Dict, Optional, Union
+from typing import TYPE_CHECKING, Any, Dict, Literal, Optional, Union, overload
 
 import boto3
 from botocore.config import Config
 
+from aws_lambda_powertools.utilities.parameters.types import TransformOptions
+
 if TYPE_CHECKING:
  from mypy_boto3_secretsmanager import SecretsManagerClient
 
@@ -116,9 +118,49 @@ def _get_multiple(self, path: str, **sdk_options) -> Dict[str, str]:
  raise NotImplementedError()
 
 
+@overload
+def get_secret(
+ name: str,
+ transform: None = None,
+ force_fetch: bool = False,
+ max_age: Optional[int] = None,
+ **sdk_options,
+) -> str: ...
+
+
+@overload
+def get_secret(
+ name: str,
+ transform: Literal["json"],
+ force_fetch: bool = False,
+ max_age: Optional[int] = None,
+ **sdk_options,
+) -> dict: ...
+
+
+@overload
+def get_secret(
+ name: str,
+ transform: Literal["binary"],
+ force_fetch: bool = False,
+ max_age: Optional[int] = None,
+ **sdk_options,
+) -> Union[str, dict, bytes]: ...
+
+
+@overload
+def get_secret(
+ name: str,
+ transform: Literal["auto"],
+ force_fetch: bool = False,
+ max_age: Optional[int] = None,
+ **sdk_options,
+) -> bytes: ...
+
+
 def get_secret(
  name: str,
- transform: Optional[str] = None,
+ transform: TransformOptions = None,
  force_fetch: bool = False,
  max_age: Optional[int] = None,
  **sdk_options,