chore(next => main): release 0.1.1

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0"
+  ".": "0.1.1"
 }

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.1.1 (2023-09-11)
+
+Full Changelog: [v0.1.0...v0.1.1](https://github.com/Finch-API/finch-api-python/compare/v0.1.0...v0.1.1)
+
+### Features
+
+* add webhook verification methods ([#89](https://github.com/Finch-API/finch-api-python/issues/89)) ([483ffef](https://github.com/Finch-API/finch-api-python/commit/483ffefdaf118a1f9d496dfb5309ced17fe1ffb5))
+
+
+### Bug Fixes
+
+* **client:** properly handle optional file params ([#88](https://github.com/Finch-API/finch-api-python/issues/88)) ([77b9914](https://github.com/Finch-API/finch-api-python/commit/77b991409d71ca0e608082f54c00824f00d0841d))
+* **pagination:** don't duplicate shared types ([#86](https://github.com/Finch-API/finch-api-python/issues/86)) ([3f5d18f](https://github.com/Finch-API/finch-api-python/commit/3f5d18f2a71488e6d5248acaed8e9b68c1d6a15d))
+
+
+### Chores
+
+* **internal:** add example for configuration ([#81](https://github.com/Finch-API/finch-api-python/issues/81)) ([a71605a](https://github.com/Finch-API/finch-api-python/commit/a71605a090760aa91120c16265f81bd742376d04))
+* **internal:** minor formatting changes ([#87](https://github.com/Finch-API/finch-api-python/issues/87)) ([f940fb2](https://github.com/Finch-API/finch-api-python/commit/f940fb2320ce901025eb34f6fbab42a70f80dd37))
+* **internal:** minor restructuring ([#84](https://github.com/Finch-API/finch-api-python/issues/84)) ([fafab61](https://github.com/Finch-API/finch-api-python/commit/fafab61d4b247255be99c3c57d7e8975c8ee73ad))
+* **internal:** minor update ([#91](https://github.com/Finch-API/finch-api-python/issues/91)) ([1bd2f68](https://github.com/Finch-API/finch-api-python/commit/1bd2f68229cb690b04b2610f0e3bc7cc7c8932d4))
+* **internal:** update base client ([#90](https://github.com/Finch-API/finch-api-python/issues/90)) ([ee7284a](https://github.com/Finch-API/finch-api-python/commit/ee7284a84d96158765307011cf8a674b17579894))
+* **internal:** update pyright ([#94](https://github.com/Finch-API/finch-api-python/issues/94)) ([9209bca](https://github.com/Finch-API/finch-api-python/commit/9209bca492b41adbd91b00f13d48570e44954e1e))
+* **internal:** updates ([#93](https://github.com/Finch-API/finch-api-python/issues/93)) ([01662d9](https://github.com/Finch-API/finch-api-python/commit/01662d9c27a615ae0a638a55df606a77bc98ccbb))
+
+
+### Documentation
+
+* **readme:** add link to api.md ([#92](https://github.com/Finch-API/finch-api-python/issues/92)) ([4770119](https://github.com/Finch-API/finch-api-python/commit/477011938cf7128f06364fa69db8dd9fa244f5b8))
+* **readme:** reference pydantic helpers ([#85](https://github.com/Finch-API/finch-api-python/issues/85)) ([95d0870](https://github.com/Finch-API/finch-api-python/commit/95d087023e69a17aabcc18521078ee2fad106bf7))
+
 ## 0.1.0 (2023-08-29)
 
 Full Changelog: [v0.0.11...v0.1.0](https://github.com/Finch-API/finch-api-python/compare/v0.0.11...v0.1.0)

README.md

@@ -18,6 +18,8 @@ pip install finch-api
 
 ## Usage
 
+The full API of this library can be found in [api.md](https://www.github.com/Finch-API/finch-api-python/blob/main/api.md).
+
 ```python
 from finch import Finch
 
@@ -57,9 +59,9 @@ Functionality between the synchronous and asynchronous clients is otherwise iden
 
 ## Using Types
 
-Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict), while responses are [Pydantic](https://pydantic-docs.helpmanual.io/) models. This helps provide autocomplete and documentation within your editor.
+Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Responses are [Pydantic models](https://docs.pydantic.dev), which provide helper methods for things like serializing back into json ([v1](https://docs.pydantic.dev/1.10/usage/models/), [v2](https://docs.pydantic.dev/latest/usage/serialization/)). To get a dictionary, you can call `dict(model)`.
 
-If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `"basic"`.
+This helps provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `"basic"`.
 
 ## Pagination
 
@@ -141,6 +143,29 @@ client.hris.directory.list_individuals(
 )
 ```
 
+## Webhook Verification
+
+We provide helper methods for verifying that a webhook request came from Finch, and not a malicious third party.
+
+You can use `finch.webhooks.verify_signature(body: string, headers, secret?) -> None` or `finch.webhooks.unwrap(body: string, headers, secret?) -> Payload`,
+both of which will raise an error if the signature is invalid.
+
+Note that the "body" parameter must be the raw JSON string sent from the server (do not parse it first).
+The `.unwrap()` method can parse this JSON for you into a `Payload` object.
+
+For example, in [FastAPI](https://fastapi.tiangolo.com/):
+
+```py
+@app.post('/my-webhook-handler')
+async def handler(request: Request):
+    body = await request.body()
+    secret = os.environ['FINCH_WEBHOOK_SECRET']  # env var used by default; explicit here.
+    payload = client.webhooks.unwrap(body, request.headers, secret)
+    print(payload)
+
+    return {'ok': True}
+```
+
 ## Handling errors
 
 When the library is unable to connect to the API (e.g., due to network connection problems or a timeout), a subclass of `finch.APIConnectionError` is raised.

api.md

@@ -223,3 +223,10 @@ Methods:
 
 - <code title="post /disconnect">client.account.<a href="./src/finch/resources/account.py">disconnect</a>() -> <a href="./src/finch/types/disconnect_response.py">DisconnectResponse</a></code>
 - <code title="get /introspect">client.account.<a href="./src/finch/resources/account.py">introspect</a>() -> <a href="./src/finch/types/introspection.py">Introspection</a></code>
+
+# Webhooks
+
+Methods:
+
+- <code>client.webhooks.<a href="./src/finch/resources/webhooks.py">unwrap</a>(\*args) -> object</code>
+- <code>client.webhooks.<a href="./src/finch/resources/webhooks.py">verify_signature</a>(\*args) -> None</code>

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "finch-api"
-version = "0.1.0"
+version = "0.1.1"
 description = "Client library for the Finch API"
 readme = "README.md"
 authors = ["Finch <[email protected]>"]
@@ -21,7 +21,7 @@ distro = ">= 1.7.0, < 2"
 
 
 [tool.poetry.group.dev.dependencies]
-pyright = "1.1.318"
+pyright = "1.1.326"
 mypy = "1.4.1"
 black = "23.3.0"
 respx = "0.19.2"
@@ -34,6 +34,7 @@ nox = "^2023.4.22"
 nox-poetry = "^1.0.3"
 
 
+
 [build-system]
 requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"

src/finch/_base_client.py

@@ -24,7 +24,7 @@
     overload,
 )
 from functools import lru_cache
-from typing_extensions import Literal, get_origin
+from typing_extensions import Literal, get_args, get_origin
 
 import anyio
 import httpx
@@ -458,6 +458,14 @@ def _serialize_multipartform(self, data: Mapping[object, object]) -> dict[str, o
             serialized[key] = value
         return serialized
 
+    def _extract_stream_chunk_type(self, stream_cls: type) -> type:
+        args = get_args(stream_cls)
+        if not args:
+            raise TypeError(
+                f"Expected stream_cls to have been given a generic type argument, e.g. Stream[Foo] but received {stream_cls}",
+            )
+        return cast(type, args[0])
+
     def _process_response(
         self,
         *,
@@ -793,7 +801,10 @@ def _request(
             raise APIConnectionError(request=request) from err
 
         if stream:
-            stream_cls = stream_cls or cast("type[_StreamT] | None", self._default_stream_cls)
+            if stream_cls:
+                return stream_cls(cast_to=self._extract_stream_chunk_type(stream_cls), response=response, client=self)
+
+            stream_cls = cast("type[_StreamT] | None", self._default_stream_cls)
             if stream_cls is None:
                 raise MissingStreamClassError()
             return stream_cls(cast_to=cast_to, response=response, client=self)
@@ -1156,7 +1167,10 @@ async def _request(
             raise APIConnectionError(request=request) from err
 
         if stream:
-            stream_cls = stream_cls or cast("type[_AsyncStreamT] | None", self._default_stream_cls)
+            if stream_cls:
+                return stream_cls(cast_to=self._extract_stream_chunk_type(stream_cls), response=response, client=self)
+
+            stream_cls = cast("type[_AsyncStreamT] | None", self._default_stream_cls)
             if stream_cls is None:
                 raise MissingStreamClassError()
             return stream_cls(cast_to=cast_to, response=response, client=self)

src/finch/_client.py

@@ -49,17 +49,20 @@ class Finch(SyncAPIClient):
     ats: resources.ATS
     providers: resources.Providers
     account: resources.Account
+    webhooks: resources.Webhooks
 
     # client options
     access_token: str | None
     client_id: str | None
     client_secret: str | None
+    webhook_secret: str | None
 
     def __init__(
         self,
         *,
         client_id: str | None = None,
         client_secret: str | None = None,
+        webhook_secret: str | None = None,
         base_url: Optional[str] = None,
         access_token: Optional[str] = None,
         timeout: Union[float, Timeout, None] = DEFAULT_TIMEOUT,
@@ -87,6 +90,7 @@ def __init__(
         This automatically infers the following arguments from their corresponding environment variables if they are not provided:
         - `client_id` from `FINCH_CLIENT_ID`
         - `client_secret` from `FINCH_CLIENT_SECRET`
+        - `webhook_secret` from `FINCH_WEBHOOK_SECRET`
         """
         self.access_token = access_token
 
@@ -96,6 +100,9 @@ def __init__(
         client_secret_envvar = os.environ.get("FINCH_CLIENT_SECRET", None)
         self.client_secret = client_secret or client_secret_envvar or None
 
+        webhook_secret_envvar = os.environ.get("FINCH_WEBHOOK_SECRET", None)
+        self.webhook_secret = webhook_secret or webhook_secret_envvar or None
+
         if base_url is None:
             base_url = f"https://api.tryfinch.com"
 
@@ -116,6 +123,7 @@ def __init__(
         self.ats = resources.ATS(self)
         self.providers = resources.Providers(self)
         self.account = resources.Account(self)
+        self.webhooks = resources.Webhooks(self)
 
     @property
     def qs(self) -> Querystring:
@@ -151,6 +159,7 @@ def copy(
         *,
         client_id: str | None = None,
         client_secret: str | None = None,
+        webhook_secret: str | None = None,
         access_token: str | None = None,
         base_url: str | None = None,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
@@ -189,6 +198,7 @@ def copy(
         return self.__class__(
             client_id=client_id or self.client_id,
             client_secret=client_secret or self.client_secret,
+            webhook_secret=webhook_secret or self.webhook_secret,
             base_url=base_url or str(self.base_url),
             access_token=access_token or self.access_token,
             timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
@@ -272,17 +282,20 @@ class AsyncFinch(AsyncAPIClient):
     ats: resources.AsyncATS
     providers: resources.AsyncProviders
     account: resources.AsyncAccount
+    webhooks: resources.AsyncWebhooks
 
     # client options
     access_token: str | None
     client_id: str | None
     client_secret: str | None
+    webhook_secret: str | None
 
     def __init__(
         self,
         *,
         client_id: str | None = None,
         client_secret: str | None = None,
+        webhook_secret: str | None = None,
         base_url: Optional[str] = None,
         access_token: Optional[str] = None,
         timeout: Union[float, Timeout, None] = DEFAULT_TIMEOUT,
@@ -310,6 +323,7 @@ def __init__(
         This automatically infers the following arguments from their corresponding environment variables if they are not provided:
         - `client_id` from `FINCH_CLIENT_ID`
         - `client_secret` from `FINCH_CLIENT_SECRET`
+        - `webhook_secret` from `FINCH_WEBHOOK_SECRET`
         """
         self.access_token = access_token
 
@@ -319,6 +333,9 @@ def __init__(
         client_secret_envvar = os.environ.get("FINCH_CLIENT_SECRET", None)
         self.client_secret = client_secret or client_secret_envvar or None
 
+        webhook_secret_envvar = os.environ.get("FINCH_WEBHOOK_SECRET", None)
+        self.webhook_secret = webhook_secret or webhook_secret_envvar or None
+
         if base_url is None:
             base_url = f"https://api.tryfinch.com"
 
@@ -339,6 +356,7 @@ def __init__(
         self.ats = resources.AsyncATS(self)
         self.providers = resources.AsyncProviders(self)
         self.account = resources.AsyncAccount(self)
+        self.webhooks = resources.AsyncWebhooks(self)
 
     @property
     def qs(self) -> Querystring:
@@ -374,6 +392,7 @@ def copy(
         *,
         client_id: str | None = None,
         client_secret: str | None = None,
+        webhook_secret: str | None = None,
         access_token: str | None = None,
         base_url: str | None = None,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
@@ -412,6 +431,7 @@ def copy(
         return self.__class__(
             client_id=client_id or self.client_id,
             client_secret=client_secret or self.client_secret,
+            webhook_secret=webhook_secret or self.webhook_secret,
             base_url=base_url or str(self.base_url),
             access_token=access_token or self.access_token,
             timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,

src/finch/_compat.py

@@ -120,10 +120,10 @@ def model_copy(model: _ModelT) -> _ModelT:
     return model.copy()  # type: ignore
 
 
-def model_json(model: pydantic.BaseModel) -> str:
+def model_json(model: pydantic.BaseModel, *, indent: int | None = None) -> str:
     if PYDANTIC_V2:
-        return model.model_dump_json()
-    return model.json()  # type: ignore
+        return model.model_dump_json(indent=indent)
+    return model.json(indent=indent)  # type: ignore
 
 
 def model_dump(model: pydantic.BaseModel) -> dict[str, Any]:
@@ -132,6 +132,12 @@ def model_dump(model: pydantic.BaseModel) -> dict[str, Any]:
     return cast("dict[str, Any]", model.dict())  # pyright: ignore[reportDeprecated, reportUnnecessaryCast]
 
 
+def model_parse(model: type[_ModelT], data: Any) -> _ModelT:
+    if PYDANTIC_V2:
+        return model.model_validate(data)
+    return model.parse_obj(data)  # pyright: ignore[reportDeprecated]
+
+
 # generic models
 if TYPE_CHECKING:
 
@@ -147,6 +153,7 @@ class GenericModel(pydantic.BaseModel):
             ...
 
     else:
+        import pydantic.generics
 
         class GenericModel(pydantic.generics.GenericModel, pydantic.BaseModel):
             ...

src/finch/_models.py

@@ -215,7 +215,7 @@ def validate_type(*, type_: type[_T], value: object) -> _T:
     if inspect.isclass(type_) and issubclass(type_, pydantic.BaseModel):
         return cast(_T, parse_obj(type_, value))
 
-    return _validate_non_model_type(type_=type_, value=value)
+    return cast(_T, _validate_non_model_type(type_=type_, value=value))
 
 
 # our use of subclasssing here causes weirdness for type checkers,