@gusto/embedded-react-sdk 0.36.0 → 0.37.0

package/dist/types/i18next.d.ts

@@ -1353,6 +1353,112 @@ export interface EmployeeTaxes{
 "federalTwoJobs":string;
 };
 };
+export interface EmployeeTerminationsTerminateEmployee{
+"title":string;
+"subtitle":string;
+"form":{
+"lastDayOfEmployment":{
+"label":string;
+"description":string;
+};
+"payrollOption":{
+"label":string;
+"description":string;
+"options":{
+"dismissalPayroll":{
+"label":string;
+"description":string;
+};
+"regularPayroll":{
+"label":string;
+"description":string;
+};
+"anotherWay":{
+"label":string;
+"description":string;
+};
+};
+};
+};
+"alert":{
+"dismissalPayroll":{
+"label":string;
+"text":string;
+};
+"regularPayroll":{
+"label":string;
+"text":string;
+};
+"anotherWay":{
+"label":string;
+"text":string;
+};
+};
+"actions":{
+"submit":string;
+"cancel":string;
+};
+"validation":{
+"lastDayRequired":string;
+"payrollOptionRequired":string;
+};
+};
+export interface EmployeeTerminationsTerminationFlow{
+"cancelSuccess":string;
+"breadcrumbs":{
+"form":string;
+"summary":string;
+"dismissal":string;
+};
+"offCycleCreation":{
+"loading":string;
+"error":string;
+"noPeriodsError":string;
+"retry":string;
+};
+};
+export interface EmployeeTerminationsTerminationSummary{
+"title":string;
+"subtitle":string;
+"alert":{
+"success":{
+"label":string;
+};
+};
+"dates":{
+"today":string;
+"dismissed":string;
+"lastDayOfWork":string;
+"lastPayDay":string;
+};
+"offboarding":{
+"title":string;
+"runPayroll":{
+"title":string;
+"description":string;
+};
+"taxForms":{
+"title":string;
+"description":string;
+};
+"disconnectAccounts":{
+"title":string;
+"description":string;
+};
+};
+"actions":{
+"cancelTermination":string;
+"editDismissal":string;
+"runDismissalPayroll":string;
+"runOffCyclePayroll":string;
+};
+"cancelDialog":{
+"title":string;
+"body":string;
+"confirm":string;
+"cancel":string;
+};
+};
 export interface InformationRequestsInformationRequestForm{
 "title":string;
 "blockingAlert":{
@@ -1490,6 +1596,20 @@ export interface PayrollConfirmWireDetailsForm{
 "content":string;
 };
 };
+export interface PayrollDismissal{
+"breadcrumbLabel":string;
+"pageTitle":string;
+"pageDescription":string;
+"selectLabel":string;
+"selectPlaceholder":string;
+"continueCta":string;
+"emptyState":string;
+"errors":{
+"missingPayrollId":string;
+"noPayPeriodSelected":string;
+"invalidPayPeriod":string;
+};
+};
 export interface PayrollEmployeeSelection{
 "sectionTitle":string;
 "searchPlaceholder":string;
@@ -1513,6 +1633,8 @@ export interface PayrollOffCycle{
 export interface PayrollOffCycleCreation{
 "pageTitle":string;
 "pageDescription":string;
+"payPeriodSectionTitle":string;
+"payPeriodSectionDescription":string;
 "continueCta":string;
 "includeAllEmployeesLabel":string;
 "errors":{
@@ -1545,6 +1667,7 @@ export interface PayrollOffCyclePayPeriodDateForm{
 "endDateAfterStart":string;
 "startDateNotFuture":string;
 "checkDateAchLeadTime":string;
+"checkDateNotPast":string;
 };
 };
 export interface PayrollOffCycleReasonSelection{
@@ -1836,6 +1959,7 @@ export interface PayrollPayrollEditEmployee{
 "doubleOvertime":string;
 };
 "timeOffTitle":string;
+"finalPayoutTitle":string;
 "timeOffBalance":{
 "remaining":string;
 };
@@ -1947,6 +2071,11 @@ export interface PayrollPayrollList{
 "3":string;
 "4":string;
 };
+"offCycleCta":{
+"title":string;
+"description":string;
+"button":string;
+};
 };
 export interface PayrollPayrollOverview{
 "breadcrumbLabel":string;
@@ -2186,6 +2315,38 @@ export interface PayrollRecoveryCasesResubmit{
 };
 };
 };
+export interface PayrollTransition{
+"breadcrumbLabel":string;
+};
+export interface PayrollTransitionCreation{
+"breadcrumbLabel":string;
+"pageTitle":string;
+"pageDescription":string;
+"transitionExplanation":string;
+"detailsHeading":string;
+"payPeriodLabel":string;
+"payScheduleLabel":string;
+"checkDateLabel":string;
+"continueCta":string;
+"errors":{
+"missingPayrollId":string;
+"checkDateRequired":string;
+"checkDateAchLeadTime":string;
+};
+};
+export interface PayrollTransitionPayrollAlert{
+"alertTitle":string;
+"alertDescription":string;
+"runPayroll":string;
+"skipPayroll":string;
+"skipSuccessAlert":string;
+"skipDialog":{
+"title":string;
+"body":string;
+"confirmCta":string;
+"cancelCta":string;
+};
+};
 export interface PayrollWireInstructions{
 "title":string;
 "subtitle":string;
@@ -2223,12 +2384,129 @@ 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;
 "loadingOptions":string;
 "requiredField":string;
 "errorEncountered":string;
+"multipleErrorsEncountered":string;
 };
 "optionalLabel":string;
 "progressBarLabel":string;
@@ -2408,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, 'InformationRequests.InformationRequestForm': InformationRequestsInformationRequestForm, 'InformationRequests.InformationRequestList': InformationRequestsInformationRequestList, 'InformationRequests': InformationRequests, 'Payroll.Common': PayrollCommon, 'Payroll.ConfirmWireDetailsBanner': PayrollConfirmWireDetailsBanner, 'Payroll.ConfirmWireDetailsForm': PayrollConfirmWireDetailsForm, '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.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/observability.d.ts

@@ -1,45 +1,22 @@
+import { SDKError } from './sdkError';
+export type ObservabilityMetricUnit = 'ms' | 'count' | 'bytes' | 'percent';
 /**
- * Observability hook types for error tracking and performance metrics
+ * An `SDKError` enriched with internal component context for observability telemetry.
+ *
+ * Partners receive this type through `ObservabilityHook.onError`. It extends the
+ * core `SDKError` with `timestamp`, `componentName`, and `componentStack` so that
+ * error-tracking tools (e.g. Sentry) can correlate and group errors.
+ *
+ * The base `SDKError` (without these fields) is the type used in partner-facing
+ * hooks like `useEmployeeForm`, keeping the public API clean.
  */
-export type ObservabilityErrorType = 'boundary_error' | 'validation_error' | 'internal_error' | 'api_error';
-export type ObservabilityMetricUnit = 'ms' | 'count' | 'bytes' | 'percent';
-export interface ObservabilityErrorContext {
-    /** Name of the component where error occurred */
-    componentName?: string;
-    /** Props passed to the component (sanitized, no sensitive data) */
-    componentProps?: Record<string, unknown>;
-    /** For validation errors, the schema that failed */
-    validationSchema?: string;
-    /** React component stack trace */
-    componentStack?: string;
-    /** Operation ID for API-related errors */
-    operationId?: string;
-    /** HTTP status code for API errors */
-    statusCode?: number;
-    /** Request details for API errors */
-    request?: {
-        url: string;
-        method: string;
-    };
-    /** Any additional context */
-    metadata?: Record<string, unknown>;
-}
-export interface ObservabilityError {
-    /** Type of error that occurred */
-    type: ObservabilityErrorType;
-    /** Human-readable error message */
-    message: string;
-    /** Error stack trace if available */
-    stack?: string;
-    /** Context about where/how the error occurred */
-    context: ObservabilityErrorContext;
-    /**
-     * The original error object (may be undefined when sanitization.includeOriginalError is false)
-     * Default sanitization removes this to prevent PII leakage
-     */
-    originalError?: unknown;
+export interface ObservabilityError extends SDKError {
     /** When the error occurred (Unix timestamp in milliseconds) */
     timestamp: number;
+    /** SDK component where the error occurred (e.g. "Employee.Profile") */
+    componentName?: string;
+    /** React component stack trace (present only for errors caught by ErrorBoundary) */
+    componentStack?: string;
 }
 export interface ObservabilityMetric {
     /** Metric name (e.g., 'sdk.form.submit_duration', 'sdk.component.loading_duration') */
@@ -62,10 +39,10 @@ export interface SanitizationConfig {
      */
     enabled?: boolean;
     /**
-     * Whether to include the original error object. Default: false
-     * WARNING: Original errors may contain sensitive data from form inputs or API responses
+     * Whether to include the raw error object on SDKError. Default: false
+     * WARNING: Raw errors may contain sensitive data from form inputs or API responses
      */
-    includeOriginalError?: boolean;
+    includeRawError?: boolean;
     /**
      * Custom sanitization function for errors
      */
@@ -82,10 +59,6 @@ export interface SanitizationConfig {
 /**
  * Observability hook interface for SDK consumers to implement
  *
- * This hook enables error tracking and performance monitoring for the SDK.
- * Errors caught by error boundaries and validation failures will be reported through onError.
- * Performance metrics for forms, components, and flows will be reported through onMetric.
- *
  * @example
  * ```tsx
  * import * as Sentry from '@sentry/react'
@@ -95,29 +68,22 @@ export interface SanitizationConfig {
  *   config={{
  *     baseUrl: '/api/',
  *     observability: {
- *       onError: (error) => {
- *         // Create Error from sanitized data (originalError is undefined by default)
- *         const sentryError = new Error(error.message)
- *         sentryError.name = error.type
- *         if (error.stack) {
- *           sentryError.stack = error.stack
- *         }
- *
- *         Sentry.captureException(sentryError, {
- *           level: error.type === 'validation_error' ? 'warning' : 'error',
+ *       onError: (error: ObservabilityError) => {
+ *         Sentry.captureException(error.raw, {
+ *           level: error.category === 'validation_error' ? 'warning' : 'error',
  *           tags: {
- *             error_type: error.type,
- *             component: error.context.componentName,
+ *             error_category: error.category,
+ *             component: error.componentName ?? 'unknown',
+ *             http_status: String(error.httpStatus ?? ''),
  *           },
  *         })
  *       },
  *       onMetric: (metric) => {
- *         // Send to your metrics service
  *         console.log(`[Metric] ${metric.name}: ${metric.value}${metric.unit}`)
  *       },
  *       sanitization: {
  *         enabled: true,
- *         includeOriginalError: false, // Default: originalError will be undefined
+ *         includeRawError: false,
  *       }
  *     }
  *   }}
@@ -128,18 +94,18 @@ export interface SanitizationConfig {
  */
 export interface ObservabilityHook {
     /**
-     * Called when an error is caught by error boundaries or validation fails
-     * These are errors that prevent a component from rendering or operating correctly
+     * Called when an error is caught by error boundaries or form submission fails.
+     * Receives an `ObservabilityError` — an `SDKError` enriched with `componentName`
+     * and (for boundary errors) `componentStack`.
      */
     onError?: (error: ObservabilityError) => void;
     /**
-     * Called to track performance metrics for component operations
-     * Optional - can be used for tracking render times, flow completions, etc.
+     * Called to track performance metrics for component operations.
      */
     onMetric?: (metric: ObservabilityMetric) => void;
     /**
-     * Configuration for sanitizing data before sending to observability tools
-     * Default: { enabled: true, includeOriginalError: false }
+     * Configuration for sanitizing data before sending to observability tools.
+     * Default: { enabled: true, includeRawError: false }
      */
     sanitization?: SanitizationConfig;
 }

package/dist/types/sdkError.d.ts

@@ -0,0 +1,97 @@
+/**
+ * High-level classification of where/how the error originated.
+ *
+ * - `api_error` — HTTP error response from the Gusto API (422, 404, 409, 500, etc.)
+ * - `validation_error` — Client-side Zod schema validation before the request was sent
+ * - `network_error` — Network connectivity failure (connection refused, timeout, abort)
+ * - `internal_error` — Unexpected runtime error (unhandled exception, initialization failure)
+ */
+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.
+ *
+ * Use this for guard clauses and data integrity checks inside submit handler
+ * callbacks where the error should surface as an inline banner, not a crash.
+ *
+ * @example
+ * ```typescript
+ * await baseSubmitHandler(data, async () => {
+ *   const response = await createPayroll({ ... })
+ *   if (!response.payrollId) {
+ *     throw new SDKInternalError('Missing payroll ID in response')
+ *   }
+ * })
+ * ```
+ */
+export declare class SDKInternalError extends Error {
+    readonly category: SDKErrorCategory;
+    constructor(message: string, category?: SDKErrorCategory);
+}
+/**
+ * A flattened, field-level error extracted from an API response.
+ *
+ * For API errors with `errors[]`, nested structures are recursively flattened
+ * into leaf entries. The `field` property is the dot-separated camelCase path
+ * (e.g. `"states.CA.filingStatus.value"`).
+ */
+export interface SDKFieldError {
+    /** Dot-separated camelCase field path (e.g. "firstName", "states.CA.filingStatus.value") */
+    field: string;
+    /** API error category (e.g. "invalid_attribute_value", "invalid_operation", "payroll_blocker") */
+    category: string;
+    /** Human-readable error message from the API */
+    message: string;
+    /** Additional metadata from the API (e.g. `{ key: "missing_bank_info" }` for payroll blockers) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The unified SDK error type for all error scenarios.
+ *
+ * This is the core error shape exposed through partner-facing hooks. For
+ * observability telemetry (which includes component context), see
+ * `ObservabilityError` in `@/types/observability`.
+ *
+ * @example
+ * ```tsx
+ * const { error } = useEmployeeForm({ employeeId })
+ *
+ * if (error) {
+ *   console.log(error.category)    // 'api_error'
+ *   console.log(error.httpStatus)  // 422
+ *   console.log(error.fieldErrors) // [{ field: 'firstName', ... }]
+ * }
+ * ```
+ */
+export interface SDKError {
+    /** High-level error classification */
+    category: SDKErrorCategory;
+    /** Human-readable error summary */
+    message: string;
+    /** HTTP status code (undefined for non-HTTP errors like network or validation) */
+    httpStatus?: number;
+    /** Flattened field-level errors from API responses. Empty array for non-field errors. */
+    fieldErrors: SDKFieldError[];
+    /**
+     * The original error object for advanced use cases.
+     * May be stripped by sanitization (controlled by `sanitization.includeRawError`).
+     */
+    raw?: unknown;
+}
+/**
+ * Normalizes any caught error into a unified `SDKError`.
+ *
+ * Classification is based purely on the error type:
+ * - `SDKInternalError` → uses the error's own `category` (default: `internal_error`)
+ * - `GustoEmbeddedError` subclasses → `api_error`
+ * - `SDKValidationError` → `validation_error`
+ * - `HTTPClientError` subclasses → `network_error`
+ * - Everything else → `internal_error`
+ */
+export declare function normalizeToSDKError(error: unknown): SDKError;

package/dist/types/sdkError.js

@@ -0,0 +1,95 @@
+import { GustoEmbeddedError as n } from "@gusto/embedded-api/models/errors/gustoembeddederror";
+import { HTTPClientError as o } from "@gusto/embedded-api/models/errors/httpclienterrors";
+import { SDKValidationError as i } from "@gusto/embedded-api/models/errors/sdkvalidationerror";
+import { getFieldErrors as c } from "../helpers/apiErrorToList.js";
+class f extends Error {
+  category;
+  constructor(r, t = "internal_error") {
+    super(r), this.name = "SDKInternalError", this.category = t;
+  }
+}
+function g(e) {
+  return e !== null && typeof e == "object" && "errors" in e && Array.isArray(e.errors);
+}
+function a(e) {
+  return {
+    field: e.errorKey,
+    message: e.message ?? "",
+    category: e.category,
+    metadata: e.metadata
+  };
+}
+function m(e) {
+  const r = e.flatMap((t) => c(t));
+  return r.length > 0 ? r.map(a) : e.filter((t) => t.message).map(a);
+}
+function u(e) {
+  return {
+    errorKey: e.errorKey ?? e.error_key ?? "",
+    category: e.category,
+    message: e.message,
+    metadata: e.metadata
+  };
+}
+function l(e) {
+  if (!e) return [];
+  try {
+    const r = JSON.parse(e);
+    if (r !== null && typeof r == "object" && "errors" in r && Array.isArray(r.errors))
+      return r.errors.filter((s) => s.message).map(u).map(a);
+  } catch {
+  }
+  return [];
+}
+function d(e, r) {
+  return e.length === 0 ? r : e.length === 1 ? "1 field has issues" : `${e.length} fields have issues`;
+}
+function K(e) {
+  if (e instanceof f)
+    return {
+      category: e.category,
+      message: e.message,
+      fieldErrors: [],
+      raw: e
+    };
+  if (e instanceof i)
+    return {
+      category: "validation_error",
+      message: typeof e.rawMessage == "string" ? e.rawMessage : e.message,
+      fieldErrors: [],
+      raw: e
+    };
+  if (e instanceof o)
+    return {
+      category: "network_error",
+      message: e.message,
+      fieldErrors: [],
+      raw: e
+    };
+  if (e instanceof n) {
+    const r = e.httpMeta.response.status, t = g(e) ? m(e.errors) : l(e.httpMeta.body);
+    return {
+      category: "api_error",
+      message: d(t, e.message),
+      httpStatus: r,
+      fieldErrors: t,
+      raw: e
+    };
+  }
+  return e instanceof Error ? {
+    category: "internal_error",
+    message: e.message,
+    fieldErrors: [],
+    raw: e
+  } : {
+    category: "internal_error",
+    message: "An unknown error occurred",
+    fieldErrors: [],
+    raw: e
+  };
+}
+export {
+  f as SDKInternalError,
+  K as normalizeToSDKError
+};
+//# sourceMappingURL=sdkError.js.map