[CON-3065] feat(gusto): Gusto-write/delete

connector/new.go

@@ -64,6 +64,7 @@ import (
 	"github.com/amp-labs/connectors/providers/gorgias"
 	"github.com/amp-labs/connectors/providers/granola"
 	"github.com/amp-labs/connectors/providers/groove"
+	"github.com/amp-labs/connectors/providers/gusto"
 	"github.com/amp-labs/connectors/providers/happyfox"
 	"github.com/amp-labs/connectors/providers/helpscoutmailbox"
 	"github.com/amp-labs/connectors/providers/heyreach"
@@ -207,6 +208,8 @@ var connectorConstructors = map[providers.Provider]outputConstructorFunc{ // nol
 	providers.Gorgias:                    wrapper(newGorgiasConnector),
 	providers.Granola:                    wrapper(newGranolaConnector),
 	providers.Groove:                     wrapper(newGrooveConnector),
+	providers.Gusto:                      wrapper(newGustoConnector),
+	providers.GustoDemo:                  wrapper(newGustoDemoConnector),
 	providers.HappyFox:                   wrapper(newHappyFoxConnector),
 	providers.HelpScoutMailbox:           wrapper(newHelpScoutMailboxConnector),
 	providers.HeyReach:                   wrapper(newHeyReachConnector),
@@ -816,6 +819,18 @@ func newGrooveConnector(
 	return groove.NewConnector(params)
 }
 
+func newGustoConnector(
+	params common.ConnectorParams,
+) (*gusto.Connector, error) {
+	return gusto.NewConnector(params)
+}
+
+func newGustoDemoConnector(
+	params common.ConnectorParams,
+) (*gusto.Connector, error) {
+	return gusto.NewDemoConnector(params)
+}
+
 func newPinterestConnector(
 	params common.ConnectorParams,
 ) (*pinterest.Connector, error) {

providers/gusto/connector.go

@@ -0,0 +1,93 @@
+// Package gusto provides a connector for the Gusto HR & Payroll API.
+// API Documentation: https://docs.gusto.com/app-integrations/reference
+// Authentication: OAuth 2.0 Authorization Code
+// Base URL: https://api.gusto.com
+package gusto
+
+import (
+	"github.com/amp-labs/connectors/common"
+	"github.com/amp-labs/connectors/internal/components"
+	"github.com/amp-labs/connectors/internal/components/deleter"
+	"github.com/amp-labs/connectors/internal/components/operations"
+	"github.com/amp-labs/connectors/internal/components/reader"
+	"github.com/amp-labs/connectors/internal/components/schema"
+	"github.com/amp-labs/connectors/internal/components/writer"
+	"github.com/amp-labs/connectors/providers"
+	"github.com/amp-labs/connectors/providers/gusto/metadata"
+)
+
+// metadataKeyCompanyID is the key under ConnectorParams.Metadata that must
+// contain the Gusto company UUID the installation is scoped to.
+const metadataKeyCompanyID = "companyId"
+
+// Connector is the Gusto connector.
+type Connector struct {
+	*components.Connector
+	common.RequireAuthenticatedClient
+
+	components.SchemaProvider
+	components.Reader
+	components.Writer
+	components.Deleter
+
+	companyID string
+}
+
+// NewConnector creates a new Gusto connector for the production environment.
+func NewConnector(params common.ConnectorParams) (*Connector, error) {
+	return components.Initialize(providers.Gusto, params, constructor(params))
+}
+
+// NewDemoConnector creates a new Gusto connector for the sandbox/demo environment.
+func NewDemoConnector(params common.ConnectorParams) (*Connector, error) {
+	return components.Initialize(providers.GustoDemo, params, constructor(params))
+}
+
+func constructor(params common.ConnectorParams) func(*components.Connector) (*Connector, error) {
+	return func(base *components.Connector) (*Connector, error) {
+		connector := &Connector{
+			Connector: base,
+			companyID: params.Metadata[metadataKeyCompanyID],
+		}
+
+		connector.SchemaProvider = schema.NewOpenAPISchemaProvider(
+			connector.ProviderContext.Module(),
+			metadata.Schemas,
+		)
+
+		connector.Reader = reader.NewHTTPReader(
+			connector.HTTPClient().Client,
+			components.NewEmptyEndpointRegistry(),
+			connector.ProviderContext.Module(),
+			operations.ReadHandlers{
+				BuildRequest:  connector.buildReadRequest,
+				ParseResponse: connector.parseReadResponse,
+				ErrorHandler:  common.InterpretError,
+			},
+		)
+
+		connector.Writer = writer.NewHTTPWriter(
+			connector.HTTPClient().Client,
+			components.NewEmptyEndpointRegistry(),
+			connector.ProviderContext.Module(),
+			operations.WriteHandlers{
+				BuildRequest:  connector.buildWriteRequest,
+				ParseResponse: connector.parseWriteResponse,
+				ErrorHandler:  common.InterpretError,
+			},
+		)
+
+		connector.Deleter = deleter.NewHTTPDeleter(
+			connector.HTTPClient().Client,
+			components.NewEmptyEndpointRegistry(),
+			connector.ProviderContext.Module(),
+			operations.DeleteHandlers{
+				BuildRequest:  connector.buildDeleteRequest,
+				ParseResponse: connector.parseDeleteResponse,
+				ErrorHandler:  common.InterpretError,
+			},
+		)
+
+		return connector, nil
+	}
+}

providers/gusto/delete.go

@@ -0,0 +1,99 @@
+package gusto
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	"github.com/amp-labs/connectors/common"
+	"github.com/amp-labs/connectors/common/urlbuilder"
+	"github.com/amp-labs/connectors/internal/datautils"
+)
+
+// Gusto delete API conventions (App Integrations track):
+//   - Most deletes are TOP-LEVEL by uuid:  DELETE /v1/{object}/{uuid}
+//   - earning_types is COMPANY-SCOPED:     DELETE /v1/companies/{cid}/earning_types/{uuid}
+//
+// Workflow-style deletes (terminations, rehire) follow a different shape and
+// are out of scope here — same reasoning as their POST/PUT counterparts in
+// write.go (proxy-only).
+//
+// API references (slug = delete-v1-{path-with-dashes}):
+// https://docs.gusto.com/app-integrations/reference/
+//   - delete-v1-employee
+//   - delete-v1-jobs-job_id
+//   - delete-v1-compensations-compensation_id
+//   - delete-v1-home_addresses-home_address_uuid
+//   - delete-v1-work_addresses-work_address_uuid
+//   - delete-v1-employee_benefits-employee_benefit_id
+//   - delete-v1-company_benefits-company_benefit_id
+//   - delete-department
+//   - delete-v1-companies-company_id-earning_types-earning_type_uuid
+
+// supportedDeleteObjects enumerates objects Gusto exposes a DELETE endpoint
+// for. Many Gusto resources have no DELETE (companies, contractors,
+// locations, payrolls, pay_schedules, garnishments, admins,
+// contractor_payments, custom_fields). For those we reject with
+// ErrOperationNotSupportedForObject.
+//
+//nolint:gochecknoglobals
+var supportedDeleteObjects = datautils.NewStringSet(
+	objectEmployees,
+	objectJobs,
+	objectCompensations,
+	objectHomeAddresses,
+	objectWorkAddresses,
+	objectEmployeeBenefits,
+	objectCompanyBenefits,
+	objectDepartments,
+	objectEarningTypes,
+)
+
+func (c *Connector) buildDeleteRequest(ctx context.Context, params common.DeleteParams) (*http.Request, error) {
+	if !supportedDeleteObjects.Has(params.ObjectName) {
+		return nil, common.ErrOperationNotSupportedForObject
+	}
+
+	url, err := c.buildDeleteURL(params)
+	if err != nil {
+		return nil, err
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, url.String(), nil)
+	if err != nil {
+		return nil, err
+	}
+
+	req.Header.Set("Accept", "application/json")
+
+	return req, nil
+}
+
+// buildDeleteURL routes earning_types through the company-scoped path and all
+// other supported objects through the flat top-level path.
+func (c *Connector) buildDeleteURL(params common.DeleteParams) (*urlbuilder.URL, error) {
+	baseURL := c.ProviderInfo().BaseURL
+
+	if companyScopedUpdate.Has(params.ObjectName) {
+		if c.companyID == "" {
+			return nil, ErrMissingCompanyID
+		}
+
+		return urlbuilder.New(baseURL, "v1", "companies", c.companyID, params.ObjectName, params.RecordId)
+	}
+
+	return urlbuilder.New(baseURL, "v1", params.ObjectName, params.RecordId)
+}
+
+func (c *Connector) parseDeleteResponse(
+	_ context.Context,
+	_ common.DeleteParams,
+	_ *http.Request,
+	response *common.JSONHTTPResponse,
+) (*common.DeleteResult, error) {
+	if response.Code != http.StatusOK && response.Code != http.StatusNoContent && response.Code != http.StatusAccepted {
+		return nil, fmt.Errorf("%w: failed to delete record: %d", common.ErrRequestFailed, response.Code)
+	}
+
+	return &common.DeleteResult{Success: true}, nil
+}

providers/gusto/delete_test.go

@@ -0,0 +1,113 @@
+package gusto
+
+import (
+	"net/http"
+	"testing"
+
+	"github.com/amp-labs/connectors"
+	"github.com/amp-labs/connectors/common"
+	"github.com/amp-labs/connectors/test/utils/mockutils/mockcond"
+	"github.com/amp-labs/connectors/test/utils/mockutils/mockserver"
+	"github.com/amp-labs/connectors/test/utils/testroutines"
+)
+
+func TestDelete(t *testing.T) { //nolint:funlen
+	t.Parallel()
+
+	tests := []testroutines.Delete{
+		{
+			Name:         "Delete object must be included",
+			Server:       mockserver.Dummy(),
+			ExpectedErrs: []error{common.ErrMissingObjects},
+		},
+		{
+			Name:         "Delete record ID must be included",
+			Input:        common.DeleteParams{ObjectName: "jobs"},
+			Server:       mockserver.Dummy(),
+			ExpectedErrs: []error{common.ErrMissingRecordID},
+		},
+		{
+			Name: "Unsupported object returns ErrOperationNotSupportedForObject",
+			// locations has no DELETE per Gusto's docs; the connector rejects.
+			Input:        common.DeleteParams{ObjectName: "locations", RecordId: "loc_001"},
+			Server:       mockserver.Dummy(),
+			ExpectedErrs: []error{common.ErrOperationNotSupportedForObject},
+		},
+		{
+			Name:  "Top-level DELETE on jobs hits /v1/jobs/{uuid}",
+			Input: common.DeleteParams{ObjectName: "jobs", RecordId: "job_001"},
+			Server: mockserver.Switch{
+				Setup: mockserver.ContentJSON(),
+				Cases: []mockserver.Case{
+					{
+						If: mockcond.And{
+							mockcond.MethodDELETE(),
+							mockcond.Path("/v1/jobs/job_001"),
+						},
+						Then: mockserver.Response(http.StatusNoContent, nil),
+					},
+				},
+				Default: mockserver.ResponseString(http.StatusInternalServerError, `{"error":"unexpected"}`),
+			}.Server(),
+			Expected: &common.DeleteResult{Success: true},
+		},
+		{
+			Name:  "Top-level DELETE on home_addresses hits /v1/home_addresses/{uuid}",
+			Input: common.DeleteParams{ObjectName: "home_addresses", RecordId: "addr_001"},
+			Server: mockserver.Switch{
+				Setup: mockserver.ContentJSON(),
+				Cases: []mockserver.Case{
+					{
+						If: mockcond.And{
+							mockcond.MethodDELETE(),
+							mockcond.Path("/v1/home_addresses/addr_001"),
+						},
+						Then: mockserver.Response(http.StatusNoContent, nil),
+					},
+				},
+				Default: mockserver.ResponseString(http.StatusInternalServerError, `{"error":"unexpected"}`),
+			}.Server(),
+			Expected: &common.DeleteResult{Success: true},
+		},
+		{
+			Name: "Company-scoped DELETE on earning_types hits /v1/companies/{cid}/earning_types/{uuid}",
+			// earning_types delete is nested under company per Gusto's docs
+			// (delete-v1-companies-company_id-earning_types-earning_type_uuid).
+			Input: common.DeleteParams{ObjectName: "earning_types", RecordId: "et_001"},
+			Server: mockserver.Switch{
+				Setup: mockserver.ContentJSON(),
+				Cases: []mockserver.Case{
+					{
+						If: mockcond.And{
+							mockcond.MethodDELETE(),
+							mockcond.Path("/v1/companies/" + testCompanyID + "/earning_types/et_001"),
+						},
+						Then: mockserver.Response(http.StatusNoContent, nil),
+					},
+				},
+				Default: mockserver.ResponseString(http.StatusInternalServerError, `{"error":"unexpected"}`),
+			}.Server(),
+			Expected: &common.DeleteResult{Success: true},
+		},
+		{
+			Name:         "DELETE earning_types without companyID returns ErrMissingCompanyID",
+			Input:        common.DeleteParams{ObjectName: "earning_types", RecordId: "et_001"},
+			Server:       mockserver.Dummy(),
+			ExpectedErrs: []error{ErrMissingCompanyID},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.Name, func(t *testing.T) {
+			t.Parallel()
+
+			tt.Run(t, func() (connectors.DeleteConnector, error) {
+				if tt.Name == "DELETE earning_types without companyID returns ErrMissingCompanyID" {
+					return constructTestWriteConnector(tt.Server.URL, "")
+				}
+
+				return constructTestWriteConnector(tt.Server.URL, testCompanyID)
+			})
+		})
+	}
+}

providers/gusto/metadata/README.md

@@ -0,0 +1,4 @@
+# Metadata
+
+Gusto does not provide a public OpenAPI specification.
+The `schemas.json` file was created manually by referencing the [Gusto API documentation](https://docs.gusto.com/app-integrations/reference).

providers/gusto/metadata/metadata.go

@@ -0,0 +1,23 @@
+package metadata
+
+import (
+	_ "embed"
+
+	"github.com/amp-labs/connectors/internal/staticschema"
+	"github.com/amp-labs/connectors/tools/fileconv"
+	"github.com/amp-labs/connectors/tools/scrapper"
+)
+
+var (
+	// There is no public OpenAPI spec available for Gusto.
+	// The schemas.json file is created manually from the API documentation.
+	// Reference: https://docs.gusto.com/app-integrations/reference
+	//
+	//go:embed schemas.json
+	schemas []byte
+
+	FileManager = scrapper.NewMetadataFileManager[staticschema.FieldMetadataMapV2]( // nolint:gochecknoglobals
+		schemas, fileconv.NewSiblingFileLocator())
+
+	Schemas = FileManager.MustLoadSchemas() // nolint:gochecknoglobals
+)