feat(api): add /forward endpoint and other updates (#115)

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 18
+configured_endpoints: 20

api.md

@@ -1,7 +1,14 @@
 # Finch
 
+Types:
+
+```python
+from finch.types import ForwardResponse
+```
+
 Methods:
 
+- <code title="post /forward">client.<a href="./src/finch/_client.py">forward</a>(\*\*<a href="src/finch/types/top_level_forward_params.py">params</a>) -> <a href="./src/finch/types/forward_response.py">ForwardResponse</a></code>
 - <code>client.<a href="./src/finch/_client.py">get_access_token</a>(\*args) -> str</code>
 - <code>client.<a href="./src/finch/_client.py">get_auth_url</a>(\*args) -> str</code>
 
@@ -138,7 +145,7 @@ Methods:
 Types:
 
 ```python
-from finch.types import Provider
+from finch.types import BenefitSupportType, Provider
 ```
 
 Methods:
@@ -164,3 +171,17 @@ 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>
+
+# Employer
+
+## Benefits
+
+Types:
+
+```python
+from finch.types.employer import RegisterCompanyBenefitsResponse
+```
+
+Methods:
+
+- <code title="post /employer/benefits/register">client.employer.benefits.<a href="./src/finch/resources/employer/benefits.py">register</a>(\*\*<a href="src/finch/types/employer/benefit_register_params.py">params</a>) -> <a href="./src/finch/types/employer/register_company_benefits_response.py">RegisterCompanyBenefitsResponse</a></code>

src/finch/_client.py

@@ -10,16 +10,20 @@
 
 from . import resources, _exceptions
 from ._qs import Querystring
+from .types import ForwardResponse, top_level_forward_params
 from ._types import (
     NOT_GIVEN,
+    Body,
     Omit,
+    Query,
     Headers,
     Timeout,
     NotGiven,
     Transport,
     ProxiesTypes,
     RequestOptions,
 )
+from ._utils import maybe_transform
 from ._version import __version__
 from ._streaming import Stream as Stream
 from ._streaming import AsyncStream as AsyncStream
@@ -30,6 +34,7 @@
     DEFAULT_MAX_RETRIES,
     SyncAPIClient,
     AsyncAPIClient,
+    make_request_options,
 )
 
 __all__ = [
@@ -50,6 +55,7 @@ class Finch(SyncAPIClient):
     providers: resources.Providers
     account: resources.Account
     webhooks: resources.Webhooks
+    employer: resources.Employer
 
     # client options
     access_token: str | None
@@ -123,6 +129,7 @@ def __init__(
         self.providers = resources.Providers(self)
         self.account = resources.Account(self)
         self.webhooks = resources.Webhooks(self)
+        self.employer = resources.Employer(self)
 
     @property
     def qs(self) -> Querystring:
@@ -216,6 +223,72 @@ def copy(
     def __del__(self) -> None:
         self.close()
 
+    def forward(
+        self,
+        *,
+        method: str,
+        route: str,
+        data: Optional[str] | NotGiven = NOT_GIVEN,
+        headers: Optional[object] | NotGiven = NOT_GIVEN,
+        params: Optional[object] | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | None | NotGiven = NOT_GIVEN,
+    ) -> ForwardResponse:
+        """The Forward API allows you to make direct requests to an employment system.
+
+        If
+        Finch’s unified API doesn’t have a data model that cleanly fits your needs, then
+        Forward allows you to push or pull data models directly against an integration’s
+        API.
+
+        Args:
+          method: The HTTP method for the forwarded request. Valid values include: `GET` , `POST`
+              , `PUT` , `DELETE` , and `PATCH`.
+
+          route: The URL route path for the forwarded request. This value must begin with a
+              forward-slash ( / ) and may only contain alphanumeric characters, hyphens, and
+              underscores.
+
+          data: The body for the forwarded request. This value must be specified as either a
+              string or a valid JSON object.
+
+          headers: The HTTP headers to include on the forwarded request. This value must be
+              specified as an object of key-value pairs. Example:
+              `{"Content-Type": "application/xml", "X-API-Version": "v1" }`
+
+          params: The query parameters for the forwarded request. This value must be specified as
+              a valid JSON object rather than a query string.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return self.post(
+            "/forward",
+            body=maybe_transform(
+                {
+                    "method": method,
+                    "route": route,
+                    "data": data,
+                    "headers": headers,
+                    "params": params,
+                },
+                top_level_forward_params.TopLevelForwardParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=ForwardResponse,
+        )
+
     def get_access_token(
         self,
         code: str,
@@ -313,6 +386,7 @@ class AsyncFinch(AsyncAPIClient):
     providers: resources.AsyncProviders
     account: resources.AsyncAccount
     webhooks: resources.AsyncWebhooks
+    employer: resources.AsyncEmployer
 
     # client options
     access_token: str | None
@@ -386,6 +460,7 @@ def __init__(
         self.providers = resources.AsyncProviders(self)
         self.account = resources.AsyncAccount(self)
         self.webhooks = resources.AsyncWebhooks(self)
+        self.employer = resources.AsyncEmployer(self)
 
     @property
     def qs(self) -> Querystring:
@@ -482,6 +557,72 @@ def __del__(self) -> None:
         except Exception:
             pass
 
+    async def forward(
+        self,
+        *,
+        method: str,
+        route: str,
+        data: Optional[str] | NotGiven = NOT_GIVEN,
+        headers: Optional[object] | NotGiven = NOT_GIVEN,
+        params: Optional[object] | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | None | NotGiven = NOT_GIVEN,
+    ) -> ForwardResponse:
+        """The Forward API allows you to make direct requests to an employment system.
+
+        If
+        Finch’s unified API doesn’t have a data model that cleanly fits your needs, then
+        Forward allows you to push or pull data models directly against an integration’s
+        API.
+
+        Args:
+          method: The HTTP method for the forwarded request. Valid values include: `GET` , `POST`
+              , `PUT` , `DELETE` , and `PATCH`.
+
+          route: The URL route path for the forwarded request. This value must begin with a
+              forward-slash ( / ) and may only contain alphanumeric characters, hyphens, and
+              underscores.
+
+          data: The body for the forwarded request. This value must be specified as either a
+              string or a valid JSON object.
+
+          headers: The HTTP headers to include on the forwarded request. This value must be
+              specified as an object of key-value pairs. Example:
+              `{"Content-Type": "application/xml", "X-API-Version": "v1" }`
+
+          params: The query parameters for the forwarded request. This value must be specified as
+              a valid JSON object rather than a query string.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return await self.post(
+            "/forward",
+            body=maybe_transform(
+                {
+                    "method": method,
+                    "route": route,
+                    "data": data,
+                    "headers": headers,
+                    "params": params,
+                },
+                top_level_forward_params.TopLevelForwardParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=ForwardResponse,
+        )
+
     async def get_access_token(
         self,
         code: str,

src/finch/resources/__init__.py

@@ -2,7 +2,19 @@
 
 from .hris import HRIS, AsyncHRIS
 from .account import Account, AsyncAccount
+from .employer import Employer, AsyncEmployer
 from .webhooks import Webhooks, AsyncWebhooks
 from .providers import Providers, AsyncProviders
 
-__all__ = ["HRIS", "AsyncHRIS", "Providers", "AsyncProviders", "Account", "AsyncAccount", "Webhooks", "AsyncWebhooks"]
+__all__ = [
+    "HRIS",
+    "AsyncHRIS",
+    "Providers",
+    "AsyncProviders",
+    "Account",
+    "AsyncAccount",
+    "Webhooks",
+    "AsyncWebhooks",
+    "Employer",
+    "AsyncEmployer",
+]

src/finch/resources/employer/__init__.py

@@ -0,0 +1,6 @@
+# File generated from our OpenAPI spec by Stainless.
+
+from .benefits import Benefits, AsyncBenefits
+from .employer import Employer, AsyncEmployer
+
+__all__ = ["Benefits", "AsyncBenefits", "Employer", "AsyncEmployer"]

src/finch/resources/employer/benefits.py

@@ -0,0 +1,110 @@
+# File generated from our OpenAPI spec by Stainless.
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ..._types import NOT_GIVEN, Body, Query, Headers, NotGiven
+from ..._utils import maybe_transform
+from ..._resource import SyncAPIResource, AsyncAPIResource
+from ...types.hris import BenefitType, BenefitFrequency
+from ..._base_client import make_request_options
+from ...types.employer import RegisterCompanyBenefitsResponse, benefit_register_params
+
+__all__ = ["Benefits", "AsyncBenefits"]
+
+
+class Benefits(SyncAPIResource):
+    def register(
+        self,
+        *,
+        description: str | NotGiven = NOT_GIVEN,
+        frequency: Optional[BenefitFrequency] | NotGiven = NOT_GIVEN,
+        type: Optional[BenefitType] | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | None | NotGiven = NOT_GIVEN,
+    ) -> RegisterCompanyBenefitsResponse:
+        """
+        **Availability: Assisted Benefits providers only**
+
+        Register existing benefits from the customer on the provider, on Finch's end.
+        Please use the `/provider` endpoint to view available types for each provider.
+
+        Args:
+          type: Type of benefit.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return self._post(
+            "/employer/benefits/register",
+            body=maybe_transform(
+                {
+                    "description": description,
+                    "frequency": frequency,
+                    "type": type,
+                },
+                benefit_register_params.BenefitRegisterParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=RegisterCompanyBenefitsResponse,
+        )
+
+
+class AsyncBenefits(AsyncAPIResource):
+    async def register(
+        self,
+        *,
+        description: str | NotGiven = NOT_GIVEN,
+        frequency: Optional[BenefitFrequency] | NotGiven = NOT_GIVEN,
+        type: Optional[BenefitType] | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | None | NotGiven = NOT_GIVEN,
+    ) -> RegisterCompanyBenefitsResponse:
+        """
+        **Availability: Assisted Benefits providers only**
+
+        Register existing benefits from the customer on the provider, on Finch's end.
+        Please use the `/provider` endpoint to view available types for each provider.
+
+        Args:
+          type: Type of benefit.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return await self._post(
+            "/employer/benefits/register",
+            body=maybe_transform(
+                {
+                    "description": description,
+                    "frequency": frequency,
+                    "type": type,
+                },
+                benefit_register_params.BenefitRegisterParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=RegisterCompanyBenefitsResponse,
+        )