chore: revert temporary commit

Author: RobertCraigie

README.md

@@ -142,6 +142,29 @@ page = client.hris.directory.list()
 print(page.page)
 ```
 
+## 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 (for example, due to network connection problems or a timeout), a subclass of `finch.APIConnectionError` is raised.

api.md

@@ -4,6 +4,13 @@
 from finch.types import ConnectionStatusType, OperationSupport, OperationSupportMatrix, Paging
 ```
 
+# Finch
+
+Methods:
+
+- <code>client.<a href="./src/finch/_client.py">get_auth_url</a>(\*args) -> str</code>
+- <code>client.<a href="./src/finch/_client.py">with_access_token</a>(\*args) -> Self</code>
+
 # AccessTokens
 
 Types:
@@ -188,6 +195,11 @@ from finch.types import (
 )
 ```
 
+Methods:
+
+- <code>client.webhooks.<a href="./src/finch/resources/webhooks.py">unwrap</a>(\*args) -> WebhookEvent</code>
+- <code>client.webhooks.<a href="./src/finch/resources/webhooks.py">verify_signature</a>(\*args) -> None</code>
+
 # RequestForwarding
 
 Types:

src/finch/_client.py

@@ -56,6 +56,7 @@ class Finch(SyncAPIClient):
     hris: resources.HRIS
     providers: resources.Providers
     account: resources.Account
+    webhooks: resources.Webhooks
     request_forwarding: resources.RequestForwarding
     jobs: resources.Jobs
     sandbox: resources.Sandbox
@@ -156,6 +157,7 @@ def __init__(
         self.hris = resources.HRIS(self)
         self.providers = resources.Providers(self)
         self.account = resources.Account(self)
+        self.webhooks = resources.Webhooks(self)
         self.request_forwarding = resources.RequestForwarding(self)
         self.jobs = resources.Jobs(self)
         self.sandbox = resources.Sandbox(self)
@@ -299,6 +301,70 @@ def copy(
     # client.with_options(timeout=10).foo.create(...)
     with_options = copy
 
+    def get_access_token(
+        self,
+        code: str,
+        *,
+        redirect_uri: str | None = None,
+    ) -> str:
+        """DEPRECATED: use client.access_tokens.create instead."""
+        if self.client_id is None:
+            raise ValueError("Expected client_id to be set in order to call get_access_token")
+
+        if self.client_secret is None:
+            raise ValueError("Expected client_secret to be set in order to call get_access_token")
+
+        response = self.post(
+            "/auth/token",
+            body={
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+                "code": code,
+                "redirect_uri": redirect_uri,
+            },
+            options={"headers": {"Authorization": Omit()}},
+            cast_to=httpx.Response,
+        )
+        data = response.json()
+        return str(data["access_token"])
+
+    def get_auth_url(
+        self,
+        *,
+        products: str,
+        redirect_uri: str,
+        sandbox: bool,
+    ) -> str:
+        """
+        Returns the authorization url which can be visited in order to obtain an
+        authorization code from Finch. The authorization code can then be exchanged for
+        an access token for the Finch api by calling get_access_token().
+        """
+        if self.client_id is None:
+            raise ValueError("Expected the client_id to be set in order to call get_auth_url")
+
+        return str(
+            httpx.URL(
+                "https://connect.tryfinch.com/authorize",
+                params={
+                    "client_id": self.client_id,
+                    "products": products,
+                    "redirect_uri": redirect_uri,
+                    "sandbox": sandbox,
+                },
+            )
+        )
+
+    def with_access_token(
+        self,
+        access_token: str,
+    ) -> Self:
+        """
+        Returns a copy of the current Finch client with the given access token for
+        authentication.
+        """
+        return self.with_options(access_token=access_token)
+
     @override
     def _make_status_error(
         self,
@@ -338,6 +404,7 @@ class AsyncFinch(AsyncAPIClient):
     hris: resources.AsyncHRIS
     providers: resources.AsyncProviders
     account: resources.AsyncAccount
+    webhooks: resources.AsyncWebhooks
     request_forwarding: resources.AsyncRequestForwarding
     jobs: resources.AsyncJobs
     sandbox: resources.AsyncSandbox
@@ -438,6 +505,7 @@ def __init__(
         self.hris = resources.AsyncHRIS(self)
         self.providers = resources.AsyncProviders(self)
         self.account = resources.AsyncAccount(self)
+        self.webhooks = resources.AsyncWebhooks(self)
         self.request_forwarding = resources.AsyncRequestForwarding(self)
         self.jobs = resources.AsyncJobs(self)
         self.sandbox = resources.AsyncSandbox(self)
@@ -581,6 +649,70 @@ def copy(
     # client.with_options(timeout=10).foo.create(...)
     with_options = copy
 
+    async def get_access_token(
+        self,
+        code: str,
+        *,
+        redirect_uri: str | None = None,
+    ) -> str:
+        """DEPRECATED: use client.access_tokens.create instead."""
+        if self.client_id is None:
+            raise ValueError("Expected client_id to be set in order to call get_access_token")
+
+        if self.client_secret is None:
+            raise ValueError("Expected client_secret to be set in order to call get_access_token")
+
+        response = await self.post(
+            "/auth/token",
+            body={
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+                "code": code,
+                "redirect_uri": redirect_uri,
+            },
+            options={"headers": {"Authorization": Omit()}},
+            cast_to=httpx.Response,
+        )
+        data = response.json()
+        return str(data["access_token"])
+
+    def get_auth_url(
+        self,
+        *,
+        products: str,
+        redirect_uri: str,
+        sandbox: bool,
+    ) -> str:
+        """
+        Returns the authorization url which can be visited in order to obtain an
+        authorization code from Finch. The authorization code can then be exchanged for
+        an access token for the Finch api by calling get_access_token().
+        """
+        if self.client_id is None:
+            raise ValueError("Expected the client_id to be set in order to call get_auth_url")
+
+        return str(
+            httpx.URL(
+                "https://connect.tryfinch.com/authorize",
+                params={
+                    "client_id": self.client_id,
+                    "products": products,
+                    "redirect_uri": redirect_uri,
+                    "sandbox": sandbox,
+                },
+            )
+        )
+
+    def with_access_token(
+        self,
+        access_token: str,
+    ) -> Self:
+        """
+        Returns a copy of the current Finch client with the given access token for
+        authentication.
+        """
+        return self.with_options(access_token=access_token)
+
     @override
     def _make_status_error(
         self,

src/finch/resources/__init__.py

@@ -32,6 +32,7 @@
     SandboxWithStreamingResponse,
     AsyncSandboxWithStreamingResponse,
 )
+from .webhooks import Webhooks, AsyncWebhooks
 from .providers import (
     Providers,
     AsyncProviders,
@@ -82,6 +83,8 @@
     "AsyncAccountWithRawResponse",
     "AccountWithStreamingResponse",
     "AsyncAccountWithStreamingResponse",
+    "Webhooks",
+    "AsyncWebhooks",
     "RequestForwarding",
     "AsyncRequestForwarding",
     "RequestForwardingWithRawResponse",

src/finch/resources/access_tokens.py

@@ -7,10 +7,7 @@
 from .. import _legacy_response
 from ..types import CreateAccessTokenResponse, access_token_create_params
 from .._types import NOT_GIVEN, Body, Query, Headers, NotGiven
-from .._utils import (
-    maybe_transform,
-    async_maybe_transform,
-)
+from .._utils import is_given, maybe_transform
 from .._compat import cached_property
 from .._resource import SyncAPIResource, AsyncAPIResource
 from .._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper
@@ -56,13 +53,27 @@ def create(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
+        if not is_given(client_id):
+            if self._client.client_id is None:
+                raise ValueError(
+                    "client_id must be provided as an argument or with the FINCH_CLIENT_ID environment variable"
+                )
+            client_id = self._client.client_id
+
+        if not is_given(client_secret):
+            if self._client.client_secret is None:
+                raise ValueError(
+                    "client_secret must be provided as an argument or with the FINCH_CLIENT_SECRET environment variable"
+                )
+            client_secret = self._client.client_secret
+
         return self._post(
             "/auth/token",
             body=maybe_transform(
                 {
-                    "code": code,
                     "client_id": client_id,
                     "client_secret": client_secret,
+                    "code": code,
                     "redirect_uri": redirect_uri,
                 },
                 access_token_create_params.AccessTokenCreateParams,
@@ -109,13 +120,27 @@ async def create(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
+        if not is_given(client_id):
+            if self._client.client_id is None:
+                raise ValueError(
+                    "client_id must be provided as an argument or with the FINCH_CLIENT_ID environment variable"
+                )
+            client_id = self._client.client_id
+
+        if not is_given(client_secret):
+            if self._client.client_secret is None:
+                raise ValueError(
+                    "client_secret must be provided as an argument or with the FINCH_CLIENT_SECRET environment variable"
+                )
+            client_secret = self._client.client_secret
+
         return await self._post(
             "/auth/token",
-            body=await async_maybe_transform(
+            body=maybe_transform(
                 {
-                    "code": code,
                     "client_id": client_id,
                     "client_secret": client_secret,
+                    "code": code,
                     "redirect_uri": redirect_uri,
                 },
                 access_token_create_params.AccessTokenCreateParams,