feat: Add API key support as alternative authentication method

Author: wizrds

asknews_sdk/client.py

@@ -17,6 +17,7 @@
 from asknews_sdk.errors import raise_from_response
 from asknews_sdk.response import APIResponse, AsyncAPIResponse
 from asknews_sdk.security import (
+    APIKey,
     AsyncTokenLoadHook,
     AsyncTokenSaveHook,
     OAuth2ClientCredentials,
@@ -47,6 +48,7 @@ def __init__(
         client_id: Optional[str],
         client_secret: Optional[str],
         scopes: Optional[Set[str]],
+        api_key: Optional[str],
         base_url: str,
         token_url: str,
         verify_ssl: bool,
@@ -64,6 +66,7 @@ def __init__(
         self.client_id = client_id
         self.client_secret = client_secret
         self.scopes = {"offline", "openid", *(scopes or set())}
+        self.api_key = api_key
         self.base_url = base_url
         self.token_url = token_url
         self.verify_ssl = verify_ssl
@@ -74,18 +77,25 @@ def __init__(
 
         if auth:
             if auth is CLIENT_DEFAULT:
-                assert self.client_id and self.client_secret, (
-                    "client_id and client_secret are required for client credentials"
-                )
-
-                self._client_auth = OAuth2ClientCredentials(
-                    client_id=self.client_id,
-                    client_secret=self.client_secret,
-                    token_url=self.token_url,
-                    scopes=self.scopes,
-                    _token_load_hook=_token_load_hook,
-                    _token_save_hook=_token_save_hook,
-                )
+                if self.api_key is not None:
+                    self._client_auth = APIKey(
+                        api_key=self.api_key,
+                    )
+                elif self.client_id is not None and self.client_secret is not None:
+                    self._client_auth = OAuth2ClientCredentials(
+                        client_id=self.client_id,
+                        client_secret=self.client_secret,
+                        token_url=self.token_url,
+                        scopes=self.scopes,
+                        _token_load_hook=_token_load_hook,
+                        _token_save_hook=_token_save_hook,
+                    )
+                else:
+                    raise ValueError(
+                        "Either api_key or client_id and client_secret are "
+                        "required for authentication. To explicitly disable "
+                        "authentication, set auth=None.",
+                    )
             else:
                 assert not isinstance(auth, Sentinel)
                 self._client_auth = auth
@@ -140,11 +150,13 @@ class APIClient(BaseAPIClient[Client, APIResponse]):
     Sync HTTP API Client
 
     :param client_id: Client ID
-    :type client_id: str
+    :type client_id: Optional[str]
     :param client_secret: Client secret
-    :type client_secret: str
+    :type client_secret: Optional[str]
     :param scopes: OAuth scopes
-    :type scopes: Set[str]
+    :type scopes: Optional[Set[str]]
+    :param api_key: API key
+    :type api_key: Optional[str]
     :param base_url: Base URL
     :type base_url: str
     :param token_url: Token URL
@@ -166,6 +178,7 @@ def __init__(
         client_id: Optional[str],
         client_secret: Optional[str],
         scopes: Optional[Set[str]],
+        api_key: Optional[str],
         base_url: str,
         token_url: str,
         verify_ssl: bool = True,
@@ -184,6 +197,7 @@ def __init__(
             client_id=client_id,
             client_secret=client_secret,
             scopes=scopes,
+            api_key=api_key,
             base_url=base_url,
             token_url=token_url,
             verify_ssl=verify_ssl,
@@ -286,11 +300,13 @@ class AsyncAPIClient(BaseAPIClient[AsyncClient, AsyncAPIResponse]):
     Base Async HTTP API Client
 
     :param client_id: Client ID
-    :type client_id: str
+    :type client_id: Optional[str]
     :param client_secret: Client secret
-    :type client_secret: str
+    :type client_secret: Optional[str]
     :param scopes: OAuth scopes
-    :type scopes: Set[str]
+    :type scopes: Optional[Set[str]]
+    :param api_key: API key
+    :type api_key: Optional[str]
     :param base_url: Base URL
     :type base_url: str
     :param token_url: Token URL
@@ -312,6 +328,7 @@ def __init__(
         client_id: Optional[str],
         client_secret: Optional[str],
         scopes: Optional[Set[str]],
+        api_key: Optional[str],
         base_url: str,
         token_url: str,
         verify_ssl: bool = True,
@@ -330,6 +347,7 @@ def __init__(
             client_id=client_id,
             client_secret=client_secret,
             scopes=scopes,
+            api_key=api_key,
             base_url=base_url,
             token_url=token_url,
             verify_ssl=verify_ssl,
@@ -393,7 +411,7 @@ async def request(
         :param stream_type: Stream type
         :type stream_type: StreamType
         :return: AsyncAPIResponse object
-        :rtype: APIResponse
+        :rtype: AsyncAPIResponse
         """
         response: Response = await self._client.send(
             self.build_api_request(

asknews_sdk/dto/alert.py

@@ -166,7 +166,7 @@ class ReportRequest(BaseModel):
             "If not provided, the default report prompt will be used. You can use {summaries} "
             "to insert the prompt optimized summaries into your report query."
         ),
-        example=[
+        examples=[
             [
                 "system",
                 "You are a helpful AI bot. Write a report based on summaries provided by the user.",
@@ -175,7 +175,7 @@ class ReportRequest(BaseModel):
         ],
     )
     model: Optional[ReportModel] = Field(
-        None, description="The model to use for the report", example="gpt-4o"
+        None, description="The model to use for the report", examples=["gpt-4o"]
     )
     logo_url: Optional[HttpUrlString] = Field(
         None, description="The logo URL to use for the report"
@@ -189,20 +189,26 @@ class CreateAlertRequest(BaseSchema):
             "The query to run for the alert. For example you ask for "
             '"I want to be alerted if there is a protest in paris"'
         ),
-        example="I want to be alerted if the president of the US says something about the economy",
+        examples=[
+            "I want to be alerted if the president of the US says something about the economy",
+        ],
     )
     cron: CronStr = Field(
         ...,
         description=(
             "The cron schedule for the alert. For example hourly is '0 * * * *'."
             " See https://crontab.run/ for more examples"
         ),
-        example="*/15 * * * *",
+        examples=[
+            "*/15 * * * *",
+        ],
     )
     model: Optional[CheckAlertModel] = Field(
         ...,
         description="The model to use for the alert check",
-        example="meta-llama/Meta-Llama-3.1-8B-Instruct",
+        examples=[
+            "meta-llama/Meta-Llama-3.1-8B-Instruct",
+        ],
     )
     share_link: Optional[HttpUrlString] = Field(
         None, description="The newsplunker share link to update when the alert triggers"
@@ -243,20 +249,26 @@ class UpdateAlertRequest(BaseSchema):
             "The query to run for the alert. For example you ask for "
             '"I want to be alerted if there is a protest in paris"'
         ),
-        example="I want to be alerted if the president of the US says something about the economy",
+        examples=[
+            "I want to be alerted if the president of the US says something about the economy",
+        ],
     )
     cron: Optional[CronStr] = Field(
         None,
         description=(
             "The cron schedule for the alert. For example hourly is '0 * * * *'."
             " See https://crontab.run/ for more examples"
         ),
-        example="*/15 * * * *",
+        examples=[
+            "*/15 * * * *",
+        ],
     )
     model: Optional[CheckAlertModel] = Field(
         None,
         description="The model to use for the alert check",
-        example="meta-llama/Meta-Llama-3.1-8B-Instruct",
+        examples=[
+            "meta-llama/Meta-Llama-3.1-8B-Instruct",
+        ],
     )
     share_link: Optional[HttpUrlString] = Field(
         None, description="The newsplunker share link to update when the alert triggers"

asknews_sdk/sdk.py

@@ -36,21 +36,30 @@ class AskNewsSDK:
 
     Usage:
 
+    ```python
+    >>> with AskNewsSDK(api_key=...) as sdk:
+    >>>    stories_response = sdk.stories.get_stories(...)
+    ```
+
+    Or
+
     ```python
     >>> with AskNewsSDK(client_id=..., client_secret=...) as sdk:
     >>>    stories_response = sdk.stories.get_stories(...)
     ```
 
-    :param client_id: The client ID for your AskNews API application.
-    :type client_id: str
-    :param client_secret: The client secret for your AskNews API application.
-    :type client_secret: str
-    :param scopes: The scopes to request for your AskNews API application.
+    :param client_id: The client ID for the AskNews API credentials.
+    :type client_id: Optional[str]
+    :param client_secret: The client secret for the AskNews API credentials.
+    :type client_secret: Optional[str]
+    :param scopes: The scopes to request for the AskNews API credentials.
     :type scopes: Optional[Set[str]]
     :param base_url: The base URL for the AskNews API.
     :type base_url: str
     :param token_url: The token URL for the AskNews API.
     :type token_url: str
+    :param api_key: An API key for the AskNews API.
+    :type api_key: Optional[str]
     :param verify_ssl: Whether or not to verify SSL certificates.
     :type verify_ssl: bool
     :param retries: The number of retries to attempt on connection errors.
@@ -72,6 +81,7 @@ def __init__(
         scopes: Optional[Set[str]] = DEFAULT_SCOPES,
         base_url: str = DEFAULT_API_BASE_URL,
         token_url: str = DEFAULT_TOKEN_URL,
+        api_key: Optional[str] = None,
         verify_ssl: bool = True,
         retries: int = 3,
         timeout: Optional[float] = None,
@@ -87,6 +97,7 @@ def __init__(
             client_id=client_id,
             client_secret=client_secret,
             scopes=scopes,
+            api_key=api_key,
             base_url=base_url,
             token_url=token_url,
             verify_ssl=verify_ssl,
@@ -134,21 +145,30 @@ class AsyncAskNewsSDK:
 
     Usage:
 
+    ```python
+    >>> async with AskNewsSDK(api_key=...) as sdk:
+    >>>    stories_response = await sdk.stories.get_stories(...)
+    ```
+
+    Or
+
     ```python
     >>> async with AskNewsSDK(client_id=..., client_secret=...) as sdk:
     >>>    stories_response = await sdk.stories.get_stories(...)
     ```
 
-    :param client_id: The client ID for your AskNews API application.
-    :type client_id: str
-    :param client_secret: The client secret for your AskNews API application.
-    :type client_secret: str
-    :param scopes: The scopes to request for your AskNews API application.
+    :param client_id: The client ID for the AskNews API credentials.
+    :type client_id: Optional[str]
+    :param client_secret: The client secret for the AskNews API credentials.
+    :type client_secret: Optional[str]
+    :param scopes: The scopes to request for the AskNews API credentials.
     :type scopes: Optional[Set[str]]
     :param base_url: The base URL for the AskNews API.
     :type base_url: str
     :param token_url: The token URL for the AskNews API.
     :type token_url: str
+    :param api_key: An API key for the AskNews API.
+    :type api_key: Optional[str]
     :param verify_ssl: Whether or not to verify SSL certificates.
     :type verify_ssl: bool
     :param retries: The number of retries to attempt on connection errors.
@@ -170,6 +190,7 @@ def __init__(
         scopes: Optional[Set[str]] = DEFAULT_SCOPES,
         base_url: str = DEFAULT_API_BASE_URL,
         token_url: str = DEFAULT_TOKEN_URL,
+        api_key: Optional[str] = None,
         verify_ssl: bool = True,
         retries: int = 3,
         timeout: Optional[float] = None,
@@ -185,6 +206,7 @@ def __init__(
             client_id=client_id,
             client_secret=client_secret,
             scopes=scopes,
+            api_key=api_key,
             base_url=base_url,
             token_url=token_url,
             verify_ssl=verify_ssl,