@gusto/embedded-react-sdk 0.37.0-rc.1 → 0.37.0

package/dist/types/i18next.d.ts

@@ -2384,6 +2384,122 @@ export interface PayrollWireInstructions{
 "confirm":string;
 };
 };
+export interface UNSTABLECompensationForm{
+"title":string;
+"editTitle":string;
+"addTitle":string;
+"jobTitle":string;
+"employeeClassification":string;
+"classificationLink":string;
+"amount":string;
+"paymentUnitLabel":string;
+"paymentUnitDescription":string;
+"adjustForMinimumWage":string;
+"adjustForMinimumWageDescription":string;
+"minimumWageLabel":string;
+"minimumWageDescription":string;
+"twoPercentStakeholderLabel":string;
+"stateWcCoveredLabel":string;
+"stateWcCoveredDescription":string;
+"stateWcCoveredYes":string;
+"stateWcCoveredNo":string;
+"stateWcClassCodeLabel":string;
+"stateWcClassCodeDescription":string;
+"submitCta":string;
+"saveNewJobCta":string;
+"flsaStatusLabels":{
+"Commission Only Exempt":string;
+"Commission Only Nonexempt":string;
+"Exempt":string;
+"Nonexempt":string;
+"Owner":string;
+"Salaried Nonexempt":string;
+};
+"paymentUnitOptions":{
+"Hour":string;
+"Month":string;
+"Paycheck":string;
+"Week":string;
+"Year":string;
+};
+"startDateLabel":string;
+"fieldValidations":{
+"startDate":{
+"REQUIRED":string;
+};
+"jobTitle":{
+"REQUIRED":string;
+};
+"flsaStatus":{
+"REQUIRED":string;
+};
+"rate":{
+"REQUIRED":string;
+"RATE_MINIMUM":string;
+"RATE_EXEMPT_THRESHOLD":string;
+};
+"paymentUnit":{
+"REQUIRED":string;
+};
+"minimumWageId":{
+"REQUIRED":string;
+};
+"stateWcClassCode":{
+"REQUIRED":string;
+};
+};
+};
+export interface UNSTABLEEmployeeDetailsForm{
+"addTitle":string;
+"editTitle":string;
+"firstNameLabel":string;
+"middleInitialLabel":string;
+"lastNameLabel":string;
+"emailLabel":string;
+"emailDescription":string;
+"dateOfBirthLabel":string;
+"ssnLabel":string;
+"selfOnboardingLabel":string;
+"selfOnboardingDescription":string;
+"createCta":string;
+"updateCta":string;
+"fieldValidations":{
+"firstName":{
+"REQUIRED":string;
+"INVALID_NAME":string;
+};
+"lastName":{
+"REQUIRED":string;
+"INVALID_NAME":string;
+};
+"email":{
+"REQUIRED":string;
+"INVALID_EMAIL":string;
+"EMAIL_REQUIRED_FOR_SELF_ONBOARDING":string;
+};
+"ssn":{
+"INVALID_SSN":string;
+};
+};
+};
+export interface UNSTABLEWorkAddressForm{
+"addTitle":string;
+"editTitle":string;
+"locationLabel":string;
+"locationDescription":string;
+"effectiveDateLabel":string;
+"effectiveDateDescription":string;
+"createCta":string;
+"updateCta":string;
+"fieldValidations":{
+"locationUuid":{
+"REQUIRED":string;
+};
+"effectiveDate":{
+"REQUIRED":string;
+};
+};
+};
 export interface common{
 "status":{
 "loading":string;
@@ -2570,6 +2686,6 @@ export interface common{
 
     interface CustomTypeOptions {
         defaultNS: 'common';
-        resources: { 'Company.Addresses': CompanyAddresses, 'Company.AssignSignatory': CompanyAssignSignatory, 'Company.BankAccount': CompanyBankAccount, 'Company.DocumentList': CompanyDocumentList, 'Company.FederalTaxes': CompanyFederalTaxes, 'Company.Industry': CompanyIndustry, 'Company.Locations': CompanyLocations, 'Company.OnboardingOverview': CompanyOnboardingOverview, 'Company.PaySchedule': CompanyPaySchedule, 'Company.SignatureForm': CompanySignatureForm, 'Company.StateTaxes': CompanyStateTaxes, 'Contractor.Address': ContractorAddress, 'Contractor.ContractorList': ContractorContractorList, 'Contractor.NewHireReport': ContractorNewHireReport, 'Contractor.PaymentMethod': ContractorPaymentMethod, 'Contractor.Payments.CreatePayment': ContractorPaymentsCreatePayment, 'Contractor.Payments.PaymentHistory': ContractorPaymentsPaymentHistory, 'Contractor.Payments.PaymentStatement': ContractorPaymentsPaymentStatement, 'Contractor.Payments.PaymentSummary': ContractorPaymentsPaymentSummary, 'Contractor.Payments.PaymentsList': ContractorPaymentsPaymentsList, 'Contractor.Profile': ContractorProfile, 'Contractor.Submit': ContractorSubmit, 'Employee.BankAccount': EmployeeBankAccount, 'Employee.Compensation': EmployeeCompensation, 'Employee.Deductions': EmployeeDeductions, 'Employee.DocumentSigner': EmployeeDocumentSigner, 'Employee.EmployeeDocuments': EmployeeEmployeeDocuments, 'Employee.EmployeeList': EmployeeEmployeeList, 'Employee.EmploymentEligibility': EmployeeEmploymentEligibility, 'Employee.FederalTaxes': EmployeeFederalTaxes, 'Employee.HomeAddress': EmployeeHomeAddress, 'Employee.I9SignatureForm': EmployeeI9SignatureForm, 'Employee.Landing': EmployeeLanding, 'Employee.OnboardingSummary': EmployeeOnboardingSummary, 'Employee.PaySchedules': EmployeePaySchedules, 'Employee.PaymentMethod': EmployeePaymentMethod, 'Employee.Profile': EmployeeProfile, 'Employee.SplitPaycheck': EmployeeSplitPaycheck, 'Employee.StateTaxes': EmployeeStateTaxes, 'Employee.Taxes': EmployeeTaxes, 'Employee.Terminations.TerminateEmployee': EmployeeTerminationsTerminateEmployee, 'Employee.Terminations.TerminationFlow': EmployeeTerminationsTerminationFlow, 'Employee.Terminations.TerminationSummary': EmployeeTerminationsTerminationSummary, 'InformationRequests.InformationRequestForm': InformationRequestsInformationRequestForm, 'InformationRequests.InformationRequestList': InformationRequestsInformationRequestList, 'InformationRequests': InformationRequests, 'Payroll.Common': PayrollCommon, 'Payroll.ConfirmWireDetailsBanner': PayrollConfirmWireDetailsBanner, 'Payroll.ConfirmWireDetailsForm': PayrollConfirmWireDetailsForm, 'Payroll.Dismissal': PayrollDismissal, 'Payroll.EmployeeSelection': PayrollEmployeeSelection, 'Payroll.GrossUpModal': PayrollGrossUpModal, 'Payroll.OffCycle': PayrollOffCycle, 'Payroll.OffCycleCreation': PayrollOffCycleCreation, 'Payroll.OffCycleDeductionsSetting': PayrollOffCycleDeductionsSetting, 'Payroll.OffCyclePayPeriodDateForm': PayrollOffCyclePayPeriodDateForm, 'Payroll.OffCycleReasonSelection': PayrollOffCycleReasonSelection, 'Payroll.OffCycleTaxWithholding': PayrollOffCycleTaxWithholding, 'Payroll.PayrollBlocker': PayrollPayrollBlocker, 'Payroll.PayrollConfiguration': PayrollPayrollConfiguration, 'Payroll.PayrollEditEmployee': PayrollPayrollEditEmployee, 'Payroll.PayrollFlow': PayrollPayrollFlow, 'Payroll.PayrollHistory': PayrollPayrollHistory, 'Payroll.PayrollLanding': PayrollPayrollLanding, 'Payroll.PayrollList': PayrollPayrollList, 'Payroll.PayrollOverview': PayrollPayrollOverview, 'Payroll.PayrollReceipts': PayrollPayrollReceipts, 'Payroll.RecoveryCasesList': PayrollRecoveryCasesList, 'Payroll.RecoveryCasesResubmit': PayrollRecoveryCasesResubmit, 'Payroll.Transition': PayrollTransition, 'Payroll.TransitionCreation': PayrollTransitionCreation, 'Payroll.TransitionPayrollAlert': PayrollTransitionPayrollAlert, 'Payroll.WireInstructions': PayrollWireInstructions, 'common': common,  }
+        resources: { 'Company.Addresses': CompanyAddresses, 'Company.AssignSignatory': CompanyAssignSignatory, 'Company.BankAccount': CompanyBankAccount, 'Company.DocumentList': CompanyDocumentList, 'Company.FederalTaxes': CompanyFederalTaxes, 'Company.Industry': CompanyIndustry, 'Company.Locations': CompanyLocations, 'Company.OnboardingOverview': CompanyOnboardingOverview, 'Company.PaySchedule': CompanyPaySchedule, 'Company.SignatureForm': CompanySignatureForm, 'Company.StateTaxes': CompanyStateTaxes, 'Contractor.Address': ContractorAddress, 'Contractor.ContractorList': ContractorContractorList, 'Contractor.NewHireReport': ContractorNewHireReport, 'Contractor.PaymentMethod': ContractorPaymentMethod, 'Contractor.Payments.CreatePayment': ContractorPaymentsCreatePayment, 'Contractor.Payments.PaymentHistory': ContractorPaymentsPaymentHistory, 'Contractor.Payments.PaymentStatement': ContractorPaymentsPaymentStatement, 'Contractor.Payments.PaymentSummary': ContractorPaymentsPaymentSummary, 'Contractor.Payments.PaymentsList': ContractorPaymentsPaymentsList, 'Contractor.Profile': ContractorProfile, 'Contractor.Submit': ContractorSubmit, 'Employee.BankAccount': EmployeeBankAccount, 'Employee.Compensation': EmployeeCompensation, 'Employee.Deductions': EmployeeDeductions, 'Employee.DocumentSigner': EmployeeDocumentSigner, 'Employee.EmployeeDocuments': EmployeeEmployeeDocuments, 'Employee.EmployeeList': EmployeeEmployeeList, 'Employee.EmploymentEligibility': EmployeeEmploymentEligibility, 'Employee.FederalTaxes': EmployeeFederalTaxes, 'Employee.HomeAddress': EmployeeHomeAddress, 'Employee.I9SignatureForm': EmployeeI9SignatureForm, 'Employee.Landing': EmployeeLanding, 'Employee.OnboardingSummary': EmployeeOnboardingSummary, 'Employee.PaySchedules': EmployeePaySchedules, 'Employee.PaymentMethod': EmployeePaymentMethod, 'Employee.Profile': EmployeeProfile, 'Employee.SplitPaycheck': EmployeeSplitPaycheck, 'Employee.StateTaxes': EmployeeStateTaxes, 'Employee.Taxes': EmployeeTaxes, 'Employee.Terminations.TerminateEmployee': EmployeeTerminationsTerminateEmployee, 'Employee.Terminations.TerminationFlow': EmployeeTerminationsTerminationFlow, 'Employee.Terminations.TerminationSummary': EmployeeTerminationsTerminationSummary, 'InformationRequests.InformationRequestForm': InformationRequestsInformationRequestForm, 'InformationRequests.InformationRequestList': InformationRequestsInformationRequestList, 'InformationRequests': InformationRequests, 'Payroll.Common': PayrollCommon, 'Payroll.ConfirmWireDetailsBanner': PayrollConfirmWireDetailsBanner, 'Payroll.ConfirmWireDetailsForm': PayrollConfirmWireDetailsForm, 'Payroll.Dismissal': PayrollDismissal, 'Payroll.EmployeeSelection': PayrollEmployeeSelection, 'Payroll.GrossUpModal': PayrollGrossUpModal, 'Payroll.OffCycle': PayrollOffCycle, 'Payroll.OffCycleCreation': PayrollOffCycleCreation, 'Payroll.OffCycleDeductionsSetting': PayrollOffCycleDeductionsSetting, 'Payroll.OffCyclePayPeriodDateForm': PayrollOffCyclePayPeriodDateForm, 'Payroll.OffCycleReasonSelection': PayrollOffCycleReasonSelection, 'Payroll.OffCycleTaxWithholding': PayrollOffCycleTaxWithholding, 'Payroll.PayrollBlocker': PayrollPayrollBlocker, 'Payroll.PayrollConfiguration': PayrollPayrollConfiguration, 'Payroll.PayrollEditEmployee': PayrollPayrollEditEmployee, 'Payroll.PayrollFlow': PayrollPayrollFlow, 'Payroll.PayrollHistory': PayrollPayrollHistory, 'Payroll.PayrollLanding': PayrollPayrollLanding, 'Payroll.PayrollList': PayrollPayrollList, 'Payroll.PayrollOverview': PayrollPayrollOverview, 'Payroll.PayrollReceipts': PayrollPayrollReceipts, 'Payroll.RecoveryCasesList': PayrollRecoveryCasesList, 'Payroll.RecoveryCasesResubmit': PayrollRecoveryCasesResubmit, 'Payroll.Transition': PayrollTransition, 'Payroll.TransitionCreation': PayrollTransitionCreation, 'Payroll.TransitionPayrollAlert': PayrollTransitionPayrollAlert, 'Payroll.WireInstructions': PayrollWireInstructions, 'UNSTABLE.CompensationForm': UNSTABLECompensationForm, 'UNSTABLE.EmployeeDetailsForm': UNSTABLEEmployeeDetailsForm, 'UNSTABLE.WorkAddressForm': UNSTABLEWorkAddressForm, 'common': common,  }
     };
 }

package/dist/types/sdkError.d.ts

@@ -6,7 +6,13 @@
  * - `network_error` — Network connectivity failure (connection refused, timeout, abort)
  * - `internal_error` — Unexpected runtime error (unhandled exception, initialization failure)
  */
-export type SDKErrorCategory = 'api_error' | 'validation_error' | 'network_error' | 'internal_error';
+export declare const SDKErrorCategories: {
+    readonly API_ERROR: "api_error";
+    readonly VALIDATION_ERROR: "validation_error";
+    readonly NETWORK_ERROR: "network_error";
+    readonly INTERNAL_ERROR: "internal_error";
+};
+export type SDKErrorCategory = (typeof SDKErrorCategories)[keyof typeof SDKErrorCategories];
 /**
  * An error thrown by internal SDK logic that should be caught and normalized
  * by `baseSubmitHandler` rather than propagating to the ErrorBoundary.

package/dist/types/sdkError.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdkError.js","sources":["../../src/types/sdkError.ts"],"sourcesContent":["import type { EntityErrorObject } from '@gusto/embedded-api/models/components/entityerrorobject'\nimport { GustoEmbeddedError } from '@gusto/embedded-api/models/errors/gustoembeddederror'\nimport { HTTPClientError } from '@gusto/embedded-api/models/errors/httpclienterrors'\nimport { SDKValidationError } from '@gusto/embedded-api/models/errors/sdkvalidationerror'\nimport { getFieldErrors } from '@/helpers/apiErrorToList'\n\n/**\n * High-level classification of where/how the error originated.\n *\n * - `api_error` — HTTP error response from the Gusto API (422, 404, 409, 500, etc.)\n * - `validation_error` — Client-side Zod schema validation before the request was sent\n * - `network_error` — Network connectivity failure (connection refused, timeout, abort)\n * - `internal_error` — Unexpected runtime error (unhandled exception, initialization failure)\n */\nexport type SDKErrorCategory = 'api_error' | 'validation_error' | 'network_error' | 'internal_error'\n\n/**\n * An error thrown by internal SDK logic that should be caught and normalized\n * by `baseSubmitHandler` rather than propagating to the ErrorBoundary.\n *\n * Use this for guard clauses and data integrity checks inside submit handler\n * callbacks where the error should surface as an inline banner, not a crash.\n *\n * @example\n * ```typescript\n * await baseSubmitHandler(data, async () => {\n *   const response = await createPayroll({ ... })\n *   if (!response.payrollId) {\n *     throw new SDKInternalError('Missing payroll ID in response')\n *   }\n * })\n * ```\n */\nexport class SDKInternalError extends Error {\n  readonly category: SDKErrorCategory\n\n  constructor(message: string, category: SDKErrorCategory = 'internal_error') {\n    super(message)\n    this.name = 'SDKInternalError'\n    this.category = category\n  }\n}\n\n/**\n * A flattened, field-level error extracted from an API response.\n *\n * For API errors with `errors[]`, nested structures are recursively flattened\n * into leaf entries. The `field` property is the dot-separated camelCase path\n * (e.g. `\"states.CA.filingStatus.value\"`).\n */\nexport interface SDKFieldError {\n  /** Dot-separated camelCase field path (e.g. \"firstName\", \"states.CA.filingStatus.value\") */\n  field: string\n  /** API error category (e.g. \"invalid_attribute_value\", \"invalid_operation\", \"payroll_blocker\") */\n  category: string\n  /** Human-readable error message from the API */\n  message: string\n  /** Additional metadata from the API (e.g. `{ key: \"missing_bank_info\" }` for payroll blockers) */\n  metadata?: Record<string, unknown>\n}\n\n/**\n * The unified SDK error type for all error scenarios.\n *\n * This is the core error shape exposed through partner-facing hooks. For\n * observability telemetry (which includes component context), see\n * `ObservabilityError` in `@/types/observability`.\n *\n * @example\n * ```tsx\n * const { error } = useEmployeeForm({ employeeId })\n *\n * if (error) {\n *   console.log(error.category)    // 'api_error'\n *   console.log(error.httpStatus)  // 422\n *   console.log(error.fieldErrors) // [{ field: 'firstName', ... }]\n * }\n * ```\n */\nexport interface SDKError {\n  /** High-level error classification */\n  category: SDKErrorCategory\n\n  /** Human-readable error summary */\n  message: string\n\n  /** HTTP status code (undefined for non-HTTP errors like network or validation) */\n  httpStatus?: number\n\n  /** Flattened field-level errors from API responses. Empty array for non-field errors. */\n  fieldErrors: SDKFieldError[]\n\n  /**\n   * The original error object for advanced use cases.\n   * May be stripped by sanitization (controlled by `sanitization.includeRawError`).\n   */\n  raw?: unknown\n}\n\ninterface ErrorWithErrors {\n  errors: EntityErrorObject[]\n}\n\nfunction hasErrorsArray(error: unknown): error is ErrorWithErrors {\n  return (\n    error !== null &&\n    typeof error === 'object' &&\n    'errors' in error &&\n    Array.isArray((error as ErrorWithErrors).errors)\n  )\n}\n\nfunction toSDKFieldError(entityError: EntityErrorObject): SDKFieldError {\n  return {\n    field: entityError.errorKey,\n    message: entityError.message ?? '',\n    category: entityError.category,\n    metadata: entityError.metadata as Record<string, unknown> | undefined,\n  }\n}\n\n/**\n * Extracts and flattens field errors from an API error's `errors[]` array.\n *\n * Uses the existing `getFieldErrors` recursive traversal for nested errors,\n * with a fallback for errors in categories that `getFieldErrors` doesn't handle.\n */\nfunction extractFieldErrors(errors: EntityErrorObject[]): SDKFieldError[] {\n  const flattened = errors.flatMap(err => getFieldErrors(err))\n  if (flattened.length > 0) {\n    return flattened.map(toSDKFieldError)\n  }\n\n  return errors.filter(err => err.message).map(toSDKFieldError)\n}\n\ninterface RawAPIFieldError {\n  error_key?: string\n  errorKey?: string\n  category: string\n  message?: string\n  metadata?: Record<string, unknown>\n}\n\nfunction rawToEntityError(raw: RawAPIFieldError): EntityErrorObject {\n  return {\n    errorKey: raw.errorKey ?? raw.error_key ?? '',\n    category: raw.category,\n    message: raw.message,\n    metadata: raw.metadata,\n  }\n}\n\nfunction tryExtractFieldErrorsFromBody(body: string | undefined): SDKFieldError[] {\n  if (!body) return []\n  try {\n    const parsed: unknown = JSON.parse(body)\n    if (\n      parsed !== null &&\n      typeof parsed === 'object' &&\n      'errors' in parsed &&\n      Array.isArray((parsed as { errors: unknown }).errors)\n    ) {\n      const errors = (parsed as { errors: RawAPIFieldError[] }).errors\n      return errors\n        .filter(err => err.message)\n        .map(rawToEntityError)\n        .map(toSDKFieldError)\n    }\n  } catch {\n    // Body isn't valid JSON\n  }\n  return []\n}\n\nfunction buildApiErrorMessage(fieldErrors: SDKFieldError[], fallbackMessage: string): string {\n  if (fieldErrors.length === 0) {\n    return fallbackMessage\n  }\n  return fieldErrors.length === 1\n    ? '1 field has issues'\n    : `${fieldErrors.length} fields have issues`\n}\n\n/**\n * Normalizes any caught error into a unified `SDKError`.\n *\n * Classification is based purely on the error type:\n * - `SDKInternalError` → uses the error's own `category` (default: `internal_error`)\n * - `GustoEmbeddedError` subclasses → `api_error`\n * - `SDKValidationError` → `validation_error`\n * - `HTTPClientError` subclasses → `network_error`\n * - Everything else → `internal_error`\n */\nexport function normalizeToSDKError(error: unknown): SDKError {\n  if (error instanceof SDKInternalError) {\n    return {\n      category: error.category,\n      message: error.message,\n      fieldErrors: [],\n      raw: error,\n    }\n  }\n\n  if (error instanceof SDKValidationError) {\n    return {\n      category: 'validation_error',\n      message: typeof error.rawMessage === 'string' ? error.rawMessage : error.message,\n      fieldErrors: [],\n      raw: error,\n    }\n  }\n\n  if (error instanceof HTTPClientError) {\n    return {\n      category: 'network_error',\n      message: error.message,\n      fieldErrors: [],\n      raw: error,\n    }\n  }\n\n  if (error instanceof GustoEmbeddedError) {\n    const httpStatus = error.httpMeta.response.status\n    const fieldErrors = hasErrorsArray(error)\n      ? extractFieldErrors(error.errors)\n      : tryExtractFieldErrorsFromBody(error.httpMeta.body)\n\n    return {\n      category: 'api_error',\n      message: buildApiErrorMessage(fieldErrors, error.message),\n      httpStatus,\n      fieldErrors,\n      raw: error,\n    }\n  }\n\n  if (error instanceof Error) {\n    return {\n      category: 'internal_error',\n      message: error.message,\n      fieldErrors: [],\n      raw: error,\n    }\n  }\n\n  return {\n    category: 'internal_error',\n    message: 'An unknown error occurred',\n    fieldErrors: [],\n    raw: error,\n  }\n}\n"],"names":["SDKInternalError","message","category","hasErrorsArray","error","toSDKFieldError","entityError","extractFieldErrors","errors","flattened","err","getFieldErrors","rawToEntityError","raw","tryExtractFieldErrorsFromBody","body","parsed","buildApiErrorMessage","fieldErrors","fallbackMessage","normalizeToSDKError","SDKValidationError","HTTPClientError","GustoEmbeddedError","httpStatus"],"mappings":"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"}
+{"version":3,"file":"sdkError.js","sources":["../../src/types/sdkError.ts"],"sourcesContent":["import type { EntityErrorObject } from '@gusto/embedded-api/models/components/entityerrorobject'\nimport { GustoEmbeddedError } from '@gusto/embedded-api/models/errors/gustoembeddederror'\nimport { HTTPClientError } from '@gusto/embedded-api/models/errors/httpclienterrors'\nimport { SDKValidationError } from '@gusto/embedded-api/models/errors/sdkvalidationerror'\nimport { getFieldErrors } from '@/helpers/apiErrorToList'\n\n/**\n * High-level classification of where/how the error originated.\n *\n * - `api_error` — HTTP error response from the Gusto API (422, 404, 409, 500, etc.)\n * - `validation_error` — Client-side Zod schema validation before the request was sent\n * - `network_error` — Network connectivity failure (connection refused, timeout, abort)\n * - `internal_error` — Unexpected runtime error (unhandled exception, initialization failure)\n */\nexport const SDKErrorCategories = {\n  API_ERROR: 'api_error',\n  VALIDATION_ERROR: 'validation_error',\n  NETWORK_ERROR: 'network_error',\n  INTERNAL_ERROR: 'internal_error',\n} as const\n\nexport type SDKErrorCategory = (typeof SDKErrorCategories)[keyof typeof SDKErrorCategories]\n\n/**\n * An error thrown by internal SDK logic that should be caught and normalized\n * by `baseSubmitHandler` rather than propagating to the ErrorBoundary.\n *\n * Use this for guard clauses and data integrity checks inside submit handler\n * callbacks where the error should surface as an inline banner, not a crash.\n *\n * @example\n * ```typescript\n * await baseSubmitHandler(data, async () => {\n *   const response = await createPayroll({ ... })\n *   if (!response.payrollId) {\n *     throw new SDKInternalError('Missing payroll ID in response')\n *   }\n * })\n * ```\n */\nexport class SDKInternalError extends Error {\n  readonly category: SDKErrorCategory\n\n  constructor(message: string, category: SDKErrorCategory = 'internal_error') {\n    super(message)\n    this.name = 'SDKInternalError'\n    this.category = category\n  }\n}\n\n/**\n * A flattened, field-level error extracted from an API response.\n *\n * For API errors with `errors[]`, nested structures are recursively flattened\n * into leaf entries. The `field` property is the dot-separated camelCase path\n * (e.g. `\"states.CA.filingStatus.value\"`).\n */\nexport interface SDKFieldError {\n  /** Dot-separated camelCase field path (e.g. \"firstName\", \"states.CA.filingStatus.value\") */\n  field: string\n  /** API error category (e.g. \"invalid_attribute_value\", \"invalid_operation\", \"payroll_blocker\") */\n  category: string\n  /** Human-readable error message from the API */\n  message: string\n  /** Additional metadata from the API (e.g. `{ key: \"missing_bank_info\" }` for payroll blockers) */\n  metadata?: Record<string, unknown>\n}\n\n/**\n * The unified SDK error type for all error scenarios.\n *\n * This is the core error shape exposed through partner-facing hooks. For\n * observability telemetry (which includes component context), see\n * `ObservabilityError` in `@/types/observability`.\n *\n * @example\n * ```tsx\n * const { error } = useEmployeeForm({ employeeId })\n *\n * if (error) {\n *   console.log(error.category)    // 'api_error'\n *   console.log(error.httpStatus)  // 422\n *   console.log(error.fieldErrors) // [{ field: 'firstName', ... }]\n * }\n * ```\n */\nexport interface SDKError {\n  /** High-level error classification */\n  category: SDKErrorCategory\n\n  /** Human-readable error summary */\n  message: string\n\n  /** HTTP status code (undefined for non-HTTP errors like network or validation) */\n  httpStatus?: number\n\n  /** Flattened field-level errors from API responses. Empty array for non-field errors. */\n  fieldErrors: SDKFieldError[]\n\n  /**\n   * The original error object for advanced use cases.\n   * May be stripped by sanitization (controlled by `sanitization.includeRawError`).\n   */\n  raw?: unknown\n}\n\ninterface ErrorWithErrors {\n  errors: EntityErrorObject[]\n}\n\nfunction hasErrorsArray(error: unknown): error is ErrorWithErrors {\n  return (\n    error !== null &&\n    typeof error === 'object' &&\n    'errors' in error &&\n    Array.isArray((error as ErrorWithErrors).errors)\n  )\n}\n\nfunction toSDKFieldError(entityError: EntityErrorObject): SDKFieldError {\n  return {\n    field: entityError.errorKey,\n    message: entityError.message ?? '',\n    category: entityError.category,\n    metadata: entityError.metadata as Record<string, unknown> | undefined,\n  }\n}\n\n/**\n * Extracts and flattens field errors from an API error's `errors[]` array.\n *\n * Uses the existing `getFieldErrors` recursive traversal for nested errors,\n * with a fallback for errors in categories that `getFieldErrors` doesn't handle.\n */\nfunction extractFieldErrors(errors: EntityErrorObject[]): SDKFieldError[] {\n  const flattened = errors.flatMap(err => getFieldErrors(err))\n  if (flattened.length > 0) {\n    return flattened.map(toSDKFieldError)\n  }\n\n  return errors.filter(err => err.message).map(toSDKFieldError)\n}\n\ninterface RawAPIFieldError {\n  error_key?: string\n  errorKey?: string\n  category: string\n  message?: string\n  metadata?: Record<string, unknown>\n}\n\nfunction rawToEntityError(raw: RawAPIFieldError): EntityErrorObject {\n  return {\n    errorKey: raw.errorKey ?? raw.error_key ?? '',\n    category: raw.category,\n    message: raw.message,\n    metadata: raw.metadata,\n  }\n}\n\nfunction tryExtractFieldErrorsFromBody(body: string | undefined): SDKFieldError[] {\n  if (!body) return []\n  try {\n    const parsed: unknown = JSON.parse(body)\n    if (\n      parsed !== null &&\n      typeof parsed === 'object' &&\n      'errors' in parsed &&\n      Array.isArray((parsed as { errors: unknown }).errors)\n    ) {\n      const errors = (parsed as { errors: RawAPIFieldError[] }).errors\n      return errors\n        .filter(err => err.message)\n        .map(rawToEntityError)\n        .map(toSDKFieldError)\n    }\n  } catch {\n    // Body isn't valid JSON\n  }\n  return []\n}\n\nfunction buildApiErrorMessage(fieldErrors: SDKFieldError[], fallbackMessage: string): string {\n  if (fieldErrors.length === 0) {\n    return fallbackMessage\n  }\n  return fieldErrors.length === 1\n    ? '1 field has issues'\n    : `${fieldErrors.length} fields have issues`\n}\n\n/**\n * Normalizes any caught error into a unified `SDKError`.\n *\n * Classification is based purely on the error type:\n * - `SDKInternalError` → uses the error's own `category` (default: `internal_error`)\n * - `GustoEmbeddedError` subclasses → `api_error`\n * - `SDKValidationError` → `validation_error`\n * - `HTTPClientError` subclasses → `network_error`\n * - Everything else → `internal_error`\n */\nexport function normalizeToSDKError(error: unknown): SDKError {\n  if (error instanceof SDKInternalError) {\n    return {\n      category: error.category,\n      message: error.message,\n      fieldErrors: [],\n      raw: error,\n    }\n  }\n\n  if (error instanceof SDKValidationError) {\n    return {\n      category: 'validation_error',\n      message: typeof error.rawMessage === 'string' ? error.rawMessage : error.message,\n      fieldErrors: [],\n      raw: error,\n    }\n  }\n\n  if (error instanceof HTTPClientError) {\n    return {\n      category: 'network_error',\n      message: error.message,\n      fieldErrors: [],\n      raw: error,\n    }\n  }\n\n  if (error instanceof GustoEmbeddedError) {\n    const httpStatus = error.httpMeta.response.status\n    const fieldErrors = hasErrorsArray(error)\n      ? extractFieldErrors(error.errors)\n      : tryExtractFieldErrorsFromBody(error.httpMeta.body)\n\n    return {\n      category: 'api_error',\n      message: buildApiErrorMessage(fieldErrors, error.message),\n      httpStatus,\n      fieldErrors,\n      raw: error,\n    }\n  }\n\n  if (error instanceof Error) {\n    return {\n      category: 'internal_error',\n      message: error.message,\n      fieldErrors: [],\n      raw: error,\n    }\n  }\n\n  return {\n    category: 'internal_error',\n    message: 'An unknown error occurred',\n    fieldErrors: [],\n    raw: error,\n  }\n}\n"],"names":["SDKInternalError","message","category","hasErrorsArray","error","toSDKFieldError","entityError","extractFieldErrors","errors","flattened","err","getFieldErrors","rawToEntityError","raw","tryExtractFieldErrorsFromBody","body","parsed","buildApiErrorMessage","fieldErrors","fallbackMessage","normalizeToSDKError","SDKValidationError","HTTPClientError","GustoEmbeddedError","httpStatus"],"mappings":"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"}

package/docs/reference/endpoint-inventory.json

@@ -1118,6 +1118,98 @@
         "companyId",
         "companyUuid"
       ]
+    },
+    "UNSTABLE_Hooks.hooks.useCompensationForm": {
+      "endpoints": [
+        {
+          "method": "GET",
+          "path": "/v1/employees/:employeeId/jobs"
+        },
+        {
+          "method": "POST",
+          "path": "/v1/employees/:employeeId/jobs"
+        },
+        {
+          "method": "PUT",
+          "path": "/v1/jobs/:jobId"
+        },
+        {
+          "method": "PUT",
+          "path": "/v1/compensations/:compensationId"
+        },
+        {
+          "method": "GET",
+          "path": "/v1/locations/:locationUuid/minimum_wages"
+        },
+        {
+          "method": "GET",
+          "path": "/v1/employees/:employeeId/work_addresses"
+        },
+        {
+          "method": "GET",
+          "path": "/v1/employees/:employeeId"
+        },
+        {
+          "method": "GET",
+          "path": "/v1/companies/:companyId/federal_tax_details"
+        }
+      ],
+      "variables": [
+        "companyId",
+        "compensationId",
+        "employeeId",
+        "jobId",
+        "locationUuid"
+      ]
+    },
+    "UNSTABLE_Hooks.hooks.useEmployeeDetailsForm": {
+      "endpoints": [
+        {
+          "method": "GET",
+          "path": "/v1/employees/:employeeId"
+        },
+        {
+          "method": "POST",
+          "path": "/v1/companies/:companyId/employees"
+        },
+        {
+          "method": "PUT",
+          "path": "/v1/employees/:employeeId"
+        },
+        {
+          "method": "PUT",
+          "path": "/v1/employees/:employeeId/onboarding_status"
+        }
+      ],
+      "variables": [
+        "companyId",
+        "employeeId"
+      ]
+    },
+    "UNSTABLE_Hooks.hooks.useWorkAddressForm": {
+      "endpoints": [
+        {
+          "method": "GET",
+          "path": "/v1/companies/:companyId/locations"
+        },
+        {
+          "method": "GET",
+          "path": "/v1/employees/:employeeId/work_addresses"
+        },
+        {
+          "method": "POST",
+          "path": "/v1/employees/:employeeId/work_addresses"
+        },
+        {
+          "method": "PUT",
+          "path": "/v1/work_addresses/:workAddressUuid"
+        }
+      ],
+      "variables": [
+        "companyId",
+        "employeeId",
+        "workAddressUuid"
+      ]
     }
   },
   "flows": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusto/embedded-react-sdk",
-  "version": "0.37.0-rc.1",
+  "version": "0.37.0",
   "homepage": "https://github.com/Gusto/embedded-react-sdk",
   "bugs": {
     "url": "https://github.com/Gusto/embedded-react-sdk/issues"
@@ -81,9 +81,9 @@
     "@commitlint/config-conventional": "^20.5.0",
     "@eslint/js": "^9.39.2",
     "@playwright/test": "^1.58.2",
-    "@storybook/addon-a11y": "^10.3.1",
-    "@storybook/addon-docs": "^10.3.1",
-    "@storybook/addon-onboarding": "^10.3.1",
+    "@storybook/addon-a11y": "^10.3.3",
+    "@storybook/addon-docs": "^10.3.3",
+    "@storybook/addon-onboarding": "^10.3.3",
     "@storybook/react-vite": "^10.3.1",
     "@storybook/test-runner": "^0.24.3",
     "@testing-library/jest-dom": "^6.9.1",
@@ -95,7 +95,7 @@
     "@types/pngjs": "^6.0.5",
     "@types/react": "^19.2.14",
     "@vitejs/plugin-react-swc": "^4.3.0",
-    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/coverage-v8": "^4.1.1",
     "axe-core": "^4.11.1",
     "dotenv": "^17.3.1",
     "eslint": "^9.39.4",
@@ -104,7 +104,7 @@
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^6.1.1",
     "eslint-plugin-react-refresh": "^0.4.24",
-    "eslint-plugin-storybook": "^10.3.1",
+    "eslint-plugin-storybook": "^10.3.3",
     "globals": "^17.4.0",
     "husky": "^9.1.7",
     "jest-axe": "^9.0.0",
@@ -153,9 +153,9 @@
     "react-aria": "^3.44.0",
     "react-aria-components": "1.13.0",
     "react-error-boundary": "^6.1.1",
-    "react-hook-form": "^7.71.2",
-    "react-i18next": "^16.6.1",
-    "react-robot": "^1.2.0",
+    "react-hook-form": "^7.72.0",
+    "react-i18next": "^16.6.6",
+    "react-robot": "^1.2.1",
     "robot3": "^1.2.0",
     "zod": "^4.3.6"
   },