feat(api): manual updates

README.md

@@ -24,23 +24,34 @@ pip install --pre openint
 The full API of this library can be found in [api.md](api.md).
 
 ```python
+import os
 from openint import Openint
 
-client = Openint()
+client = Openint(
+    api_key=os.environ.get("OPENINT_API_KEY"),  # This is the default and can be omitted
+)
 
 response = client.get_connection()
 print(response.items)
 ```
 
+While you can provide an `api_key` keyword argument,
+we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)
+to add `OPENINT_API_KEY="My API Key"` to your `.env` file
+so that your API Key is not stored in source control.
+
 ## Async usage
 
 Simply import `AsyncOpenint` instead of `Openint` and use `await` with each API call:
 
 ```python
+import os
 import asyncio
 from openint import AsyncOpenint
 
-client = AsyncOpenint()
+client = AsyncOpenint(
+    api_key=os.environ.get("OPENINT_API_KEY"),  # This is the default and can be omitted
+)
 
 
 async def main() -> None:

src/openint/_client.py

@@ -128,6 +128,29 @@ def __init__(
     def qs(self) -> Querystring:
         return Querystring(array_format="comma")
 
+    @property
+    @override
+    def auth_headers(self) -> dict[str, str]:
+        if self._organization_auth:
+            return self._organization_auth
+        if self._customer_auth:
+            return self._customer_auth
+        return {}
+
+    @property
+    def _organization_auth(self) -> dict[str, str]:
+        api_key = self.api_key
+        if api_key is None:
+            return {}
+        return {"authorization": api_key}
+
+    @property
+    def _customer_auth(self) -> dict[str, str]:
+        customer_token = self.customer_token
+        if customer_token is None:
+            return {}
+        return {"Authorization": f"Bearer {customer_token}"}
+
     @property
     @override
     def default_headers(self) -> dict[str, str | Omit]:
@@ -137,6 +160,22 @@ def default_headers(self) -> dict[str, str | Omit]:
             **self._custom_headers,
         }
 
+    @override
+    def _validate_headers(self, headers: Headers, custom_headers: Headers) -> None:
+        if self.api_key and headers.get("authorization"):
+            return
+        if isinstance(custom_headers.get("authorization"), Omit):
+            return
+
+        if self.customer_token and headers.get("Authorization"):
+            return
+        if isinstance(custom_headers.get("Authorization"), Omit):
+            return
+
+        raise TypeError(
+            '"Could not resolve authentication method. Expected either api_key or customer_token to be set. Or for one of the `authorization` or `Authorization` headers to be explicitly omitted"'
+        )
+
     def copy(
         self,
         *,
@@ -800,6 +839,29 @@ def __init__(
     def qs(self) -> Querystring:
         return Querystring(array_format="comma")
 
+    @property
+    @override
+    def auth_headers(self) -> dict[str, str]:
+        if self._organization_auth:
+            return self._organization_auth
+        if self._customer_auth:
+            return self._customer_auth
+        return {}
+
+    @property
+    def _organization_auth(self) -> dict[str, str]:
+        api_key = self.api_key
+        if api_key is None:
+            return {}
+        return {"authorization": api_key}
+
+    @property
+    def _customer_auth(self) -> dict[str, str]:
+        customer_token = self.customer_token
+        if customer_token is None:
+            return {}
+        return {"Authorization": f"Bearer {customer_token}"}
+
     @property
     @override
     def default_headers(self) -> dict[str, str | Omit]:
@@ -809,6 +871,22 @@ def default_headers(self) -> dict[str, str | Omit]:
             **self._custom_headers,
         }
 
+    @override
+    def _validate_headers(self, headers: Headers, custom_headers: Headers) -> None:
+        if self.api_key and headers.get("authorization"):
+            return
+        if isinstance(custom_headers.get("authorization"), Omit):
+            return
+
+        if self.customer_token and headers.get("Authorization"):
+            return
+        if isinstance(custom_headers.get("Authorization"), Omit):
+            return
+
+        raise TypeError(
+            '"Could not resolve authentication method. Expected either api_key or customer_token to be set. Or for one of the `authorization` or `Authorization` headers to be explicitly omitted"'
+        )
+
     def copy(
         self,
         *,

tests/conftest.py

@@ -28,14 +28,16 @@ def pytest_collection_modifyitems(items: list[pytest.Function]) -> None:
 
 base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
 
+api_key = "My API Key"
+
 
 @pytest.fixture(scope="session")
 def client(request: FixtureRequest) -> Iterator[Openint]:
     strict = getattr(request, "param", True)
     if not isinstance(strict, bool):
         raise TypeError(f"Unexpected fixture parameter type {type(strict)}, expected {bool}")
 
-    with Openint(base_url=base_url, _strict_response_validation=strict) as client:
+    with Openint(base_url=base_url, api_key=api_key, _strict_response_validation=strict) as client:
         yield client
 
 
@@ -45,5 +47,5 @@ async def async_client(request: FixtureRequest) -> AsyncIterator[AsyncOpenint]:
     if not isinstance(strict, bool):
         raise TypeError(f"Unexpected fixture parameter type {type(strict)}, expected {bool}")
 
-    async with AsyncOpenint(base_url=base_url, _strict_response_validation=strict) as client:
+    async with AsyncOpenint(base_url=base_url, api_key=api_key, _strict_response_validation=strict) as client:
         yield client