feat: introduce unified SDKError type and ObservabilityError extension

[serikjensen]

Summary

• Introduces a universal SDKError type that normalizes all error scenarios (API, validation, network, internal) into a single structured shape with category, message, httpStatus, fieldErrors, and raw
• Creates ObservabilityError extends SDKError with timestamp, componentName, and componentStack for telemetry — keeping the partner-facing type clean
• normalizeToSDKError is a pure function of the error type with no options — classification is based solely on instanceof checks
• Updates base infrastructure (useBaseSubmit, BaseComponent, BaseLayout) to use SDKError for component state and enrich with observability context only at emission sites
• Updates components consuming field errors (FederalTaxes, StateTaxes, Taxes, PaySchedule) to derive field errors from SDKError.fieldErrors
• Removes deprecated types (ObservabilityErrorType, ObservabilityErrorContext, createObservabilityError, includeOriginalError)
• Rewrites integration guide documentation to align with new types

This is prep work for the upcoming hooks-based architecture (#1254) where partners will interact with SDKError directly.

Type Design

SDKError (partner-facing):

interface SDKError {
  category: 'api_error' | 'validation_error' | 'network_error' | 'internal_error'
  message: string
  httpStatus?: number
  fieldErrors: SDKFieldError[]
  raw?: unknown
}

ObservabilityError extends SDKError (telemetry):

interface ObservabilityError extends SDKError {
  timestamp: number
  componentName?: string
  componentStack?: string
}

Errors displaying as expected

Field errors

SDK Internal Error

Test plan

• TypeScript compilation passes (npx tsc --noEmit)
• ESLint passes on all changed files
• Build succeeds (npm run build)
• Sanitization tests pass (30 tests)
• Verified live against local API: Employee.Profile, Employee.FederalTaxes, Employee.StateTaxes, Employee.Taxes, Company.PaySchedule — all submit successfully with 0 console errors

Made with Cursor

[jeffredodd]

LGTM, thanks for the improvement.