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

.stats.yml

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

api.md

@@ -1,5 +1,13 @@
 # finchgo
 
+Response Types:
+
+- <a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go">finchgo</a>.<a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go#FinchgoForwardResponse">FinchgoForwardResponse</a>
+
+Methods:
+
+- <code title="post /forward">client.<a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go#FinchgoService.Forward">Forward</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, body <a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go">finchgo</a>.<a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go#FinchgoForwardParams">FinchgoForwardParams</a>) (<a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go">finchgo</a>.<a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go#FinchgoForwardResponse">FinchgoForwardResponse</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
+
 # HRIS
 
 Response Types:
@@ -116,6 +124,7 @@ Methods:
 
 Response Types:
 
+- <a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go">finchgo</a>.<a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go#BenefitSupportType">BenefitSupportType</a>
 - <a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go">finchgo</a>.<a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go#Provider">Provider</a>
 
 Methods:
@@ -139,3 +148,15 @@ Methods:
 Custom Methods:
 
 - VerifySignature
+
+# Employer
+
+## Benefits
+
+Response Types:
+
+- <a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go">finchgo</a>.<a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go#RegisterCompanyBenefitsResponse">RegisterCompanyBenefitsResponse</a>
+
+Methods:
+
+- <code title="post /employer/benefits/register">client.Employer.Benefits.<a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go#EmployerBenefitService.Register">Register</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, body <a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go">finchgo</a>.<a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go#EmployerBenefitRegisterParams">EmployerBenefitRegisterParams</a>) (<a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go">finchgo</a>.<a href="https://pkg.go.dev/github.com/Finch-API/finch-api-go#RegisterCompanyBenefitsResponse">RegisterCompanyBenefitsResponse</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>

client.go

@@ -3,8 +3,11 @@
 package finchgo
 
 import (
+	"context"
+	"net/http"
 	"os"
 
+	"github.com/Finch-API/finch-api-go/internal/requestconfig"
 	"github.com/Finch-API/finch-api-go/option"
 )
 
@@ -17,6 +20,7 @@ type Client struct {
 	Providers *ProviderService
 	Account   *AccountService
 	Webhooks  *WebhookService
+	Employer  *EmployerService
 }
 
 // NewClient generates a new client with the default option read from the
@@ -42,6 +46,18 @@ func NewClient(opts ...option.RequestOption) (r *Client) {
 	r.Providers = NewProviderService(opts...)
 	r.Account = NewAccountService(opts...)
 	r.Webhooks = NewWebhookService(opts...)
+	r.Employer = NewEmployerService(opts...)
 
 	return
 }
+
+// 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.
+func (r *Client) Forward(ctx context.Context, body FinchgoForwardParams, opts ...option.RequestOption) (res *FinchgoForwardResponse, err error) {
+	opts = append(r.Options[:], opts...)
+	path := "forward"
+	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
+	return
+}

employer.go

@@ -0,0 +1,26 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package finchgo
+
+import (
+	"github.com/Finch-API/finch-api-go/option"
+)
+
+// EmployerService contains methods and other services that help with interacting
+// with the Finch API. Note, unlike clients, this service does not read variables
+// from the environment automatically. You should not instantiate this service
+// directly, and instead use the [NewEmployerService] method instead.
+type EmployerService struct {
+	Options  []option.RequestOption
+	Benefits *EmployerBenefitService
+}
+
+// NewEmployerService generates a new service that applies the given options to
+// each request. These options are applied after the parent client's options (if
+// there is one), and before any request-specific options.
+func NewEmployerService(opts ...option.RequestOption) (r *EmployerService) {
+	r = &EmployerService{}
+	r.Options = opts
+	r.Benefits = NewEmployerBenefitService(opts...)
+	return
+}

employerbenefit.go

@@ -0,0 +1,72 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package finchgo
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/Finch-API/finch-api-go/internal/apijson"
+	"github.com/Finch-API/finch-api-go/internal/param"
+	"github.com/Finch-API/finch-api-go/internal/requestconfig"
+	"github.com/Finch-API/finch-api-go/option"
+)
+
+// EmployerBenefitService contains methods and other services that help with
+// interacting with the Finch API. Note, unlike clients, this service does not read
+// variables from the environment automatically. You should not instantiate this
+// service directly, and instead use the [NewEmployerBenefitService] method
+// instead.
+type EmployerBenefitService struct {
+	Options []option.RequestOption
+}
+
+// NewEmployerBenefitService generates a new service that applies the given options
+// to each request. These options are applied after the parent client's options (if
+// there is one), and before any request-specific options.
+func NewEmployerBenefitService(opts ...option.RequestOption) (r *EmployerBenefitService) {
+	r = &EmployerBenefitService{}
+	r.Options = opts
+	return
+}
+
+// **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.
+func (r *EmployerBenefitService) Register(ctx context.Context, body EmployerBenefitRegisterParams, opts ...option.RequestOption) (res *RegisterCompanyBenefitsResponse, err error) {
+	opts = append(r.Options[:], opts...)
+	path := "employer/benefits/register"
+	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
+	return
+}
+
+type RegisterCompanyBenefitsResponse struct {
+	BenefitID string `json:"benefit_id,required"`
+	JobID     string `json:"job_id,required"`
+	JSON      registerCompanyBenefitsResponseJSON
+}
+
+// registerCompanyBenefitsResponseJSON contains the JSON metadata for the struct
+// [RegisterCompanyBenefitsResponse]
+type registerCompanyBenefitsResponseJSON struct {
+	BenefitID   apijson.Field
+	JobID       apijson.Field
+	raw         string
+	ExtraFields map[string]apijson.Field
+}
+
+func (r *RegisterCompanyBenefitsResponse) UnmarshalJSON(data []byte) (err error) {
+	return apijson.UnmarshalRoot(data, r)
+}
+
+type EmployerBenefitRegisterParams struct {
+	Description param.Field[string]           `json:"description"`
+	Frequency   param.Field[BenefitFrequency] `json:"frequency"`
+	// Type of benefit.
+	Type param.Field[BenefitType] `json:"type"`
+}
+
+func (r EmployerBenefitRegisterParams) MarshalJSON() (data []byte, err error) {
+	return apijson.MarshalRoot(r)
+}

employerbenefit_test.go

@@ -0,0 +1,40 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package finchgo_test
+
+import (
+	"context"
+	"errors"
+	"os"
+	"testing"
+
+	finchgo "github.com/Finch-API/finch-api-go"
+	"github.com/Finch-API/finch-api-go/internal/testutil"
+	"github.com/Finch-API/finch-api-go/option"
+)
+
+func TestEmployerBenefitRegisterWithOptionalParams(t *testing.T) {
+	baseURL := "http://localhost:4010"
+	if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok {
+		baseURL = envURL
+	}
+	if !testutil.CheckTestServer(t, baseURL) {
+		return
+	}
+	client := finchgo.NewClient(
+		option.WithBaseURL(baseURL),
+		option.WithAccessToken("AccessToken"),
+	)
+	_, err := client.Employer.Benefits.Register(context.TODO(), finchgo.EmployerBenefitRegisterParams{
+		Description: finchgo.F("string"),
+		Frequency:   finchgo.F(finchgo.BenefitFrequencyOneTime),
+		Type:        finchgo.F(finchgo.BenefitType401k),
+	})
+	if err != nil {
+		var apierr *finchgo.Error
+		if errors.As(err, &apierr) {
+			t.Log(string(apierr.DumpRequest(true)))
+		}
+		t.Fatalf("err should be nil: %s", err.Error())
+	}
+}

finchgo.go

@@ -0,0 +1,101 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package finchgo
+
+import (
+	"github.com/Finch-API/finch-api-go/internal/apijson"
+	"github.com/Finch-API/finch-api-go/internal/param"
+)
+
+type FinchgoForwardResponse struct {
+	// A string representation of the HTTP response body of the forwarded request’s
+	// response received from the underlying integration’s API. This field may be null
+	// in the case where the upstream system’s response is empty.
+	Data string `json:"data,required,nullable"`
+	// The HTTP headers of the forwarded request’s response, exactly as received from
+	// the underlying integration’s API.
+	Headers interface{} `json:"headers,required,nullable"`
+	// An object containing details of your original forwarded request, for your ease
+	// of reference.
+	Request FinchgoForwardResponseRequest `json:"request,required"`
+	// The HTTP status code of the forwarded request’s response, exactly received from
+	// the underlying integration’s API. This value will be returned as an integer.
+	StatusCode int64 `json:"statusCode,required"`
+	JSON       finchgoForwardResponseJSON
+}
+
+// finchgoForwardResponseJSON contains the JSON metadata for the struct
+// [FinchgoForwardResponse]
+type finchgoForwardResponseJSON struct {
+	Data        apijson.Field
+	Headers     apijson.Field
+	Request     apijson.Field
+	StatusCode  apijson.Field
+	raw         string
+	ExtraFields map[string]apijson.Field
+}
+
+func (r *FinchgoForwardResponse) UnmarshalJSON(data []byte) (err error) {
+	return apijson.UnmarshalRoot(data, r)
+}
+
+// An object containing details of your original forwarded request, for your ease
+// of reference.
+type FinchgoForwardResponseRequest struct {
+	// The body that was specified for the forwarded request. If a value was not
+	// specified in the original request, this value will be returned as null ;
+	// otherwise, this value will always be returned as a string.
+	Data string `json:"data,required,nullable"`
+	// The specified HTTP headers that were included in the forwarded request. If no
+	// headers were specified, this will be returned as `null`.
+	Headers interface{} `json:"headers,required,nullable"`
+	// The HTTP method that was specified for the forwarded request. Valid values
+	// include: `GET` , `POST` , `PUT` , `DELETE` , and `PATCH`.
+	Method string `json:"method,required"`
+	// The query parameters that were included in the forwarded request. If no query
+	// parameters were specified, this will be returned as `null`.
+	Params interface{} `json:"params,required,nullable"`
+	// The URL route path that was specified for the forwarded request.
+	Route string `json:"route,required"`
+	JSON  finchgoForwardResponseRequestJSON
+}
+
+// finchgoForwardResponseRequestJSON contains the JSON metadata for the struct
+// [FinchgoForwardResponseRequest]
+type finchgoForwardResponseRequestJSON struct {
+	Data        apijson.Field
+	Headers     apijson.Field
+	Method      apijson.Field
+	Params      apijson.Field
+	Route       apijson.Field
+	raw         string
+	ExtraFields map[string]apijson.Field
+}
+
+func (r *FinchgoForwardResponseRequest) UnmarshalJSON(data []byte) (err error) {
+	return apijson.UnmarshalRoot(data, r)
+}
+
+type FinchgoForwardParams struct {
+	// The HTTP method for the forwarded request. Valid values include: `GET` , `POST`
+	// , `PUT` , `DELETE` , and `PATCH`.
+	Method param.Field[string] `json:"method,required"`
+	// 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.
+	Route param.Field[string] `json:"route,required"`
+	// The body for the forwarded request. This value must be specified as either a
+	// string or a valid JSON object.
+	Data param.Field[string] `json:"data"`
+	// 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" }`
+	Headers param.Field[interface{}] `json:"headers"`
+	// The query parameters for the forwarded request. This value must be specified as
+	// a valid JSON object rather than a query string.
+	Params param.Field[interface{}] `json:"params"`
+}
+
+func (r FinchgoForwardParams) MarshalJSON() (data []byte, err error) {
+	return apijson.MarshalRoot(r)
+}

finchgo_test.go

@@ -0,0 +1,42 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package finchgo_test
+
+import (
+	"context"
+	"errors"
+	"os"
+	"testing"
+
+	finchgo "github.com/Finch-API/finch-api-go"
+	"github.com/Finch-API/finch-api-go/internal/testutil"
+	"github.com/Finch-API/finch-api-go/option"
+)
+
+func TestFinchgoForwardWithOptionalParams(t *testing.T) {
+	baseURL := "http://localhost:4010"
+	if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok {
+		baseURL = envURL
+	}
+	if !testutil.CheckTestServer(t, baseURL) {
+		return
+	}
+	client := finchgo.NewClient(
+		option.WithBaseURL(baseURL),
+		option.WithAccessToken("AccessToken"),
+	)
+	_, err := client.Forward(context.TODO(), finchgo.FinchgoForwardParams{
+		Method:  finchgo.F("string"),
+		Route:   finchgo.F("string"),
+		Data:    finchgo.F("string"),
+		Headers: finchgo.F[any](map[string]interface{}{}),
+		Params:  finchgo.F[any](map[string]interface{}{}),
+	})
+	if err != nil {
+		var apierr *finchgo.Error
+		if errors.As(err, &apierr) {
+			t.Log(string(apierr.DumpRequest(true)))
+		}
+		t.Fatalf("err should be nil: %s", err.Error())
+	}
+}

hris.go

@@ -122,7 +122,7 @@ func (r *Location) UnmarshalJSON(data []byte) (err error) {
 
 type Money struct {
 	// Amount for money object (in cents)
-	Amount   int64  `json:"amount"`
+	Amount   int64  `json:"amount,nullable"`
 	Currency string `json:"currency"`
 	JSON     moneyJSON
 }

hrisbenefit.go

@@ -125,6 +125,7 @@ type BenefitFrequency string
 const (
 	BenefitFrequencyOneTime       BenefitFrequency = "one_time"
 	BenefitFrequencyEveryPaycheck BenefitFrequency = "every_paycheck"
+	BenefitFrequencyMonthly       BenefitFrequency = "monthly"
 )
 
 // Type of benefit.