feat(SDK-492): add observability hooks with PII protection

[dmortal]

Summary

Adds comprehensive observability hooks for error tracking and performance monitoring with built-in PII protection. SDK consumers can now integrate with tools like Sentry, Datadog, or custom monitoring solutions to track errors and performance metrics.

Usage Example:

import { GustoProvider } from '@gusto/embedded-react-sdk'
import type { ObservabilityHook } from '@gusto/embedded-react-sdk'
import * as Sentry from '@sentry/react'

const observability: ObservabilityHook = {
  onError: (error) => {
    Sentry.captureException(error.originalError, {
      level: error.type === 'validation_error' ? 'warning' : 'error',
      tags: {
        error_type: error.type,
        component: error.context.componentName, // Automatically set by SDK
      },
    })
  },
  onMetric: (metric) => {
    // Track performance metrics
    console.log(`[Metric] ${metric.name}: ${metric.value}${metric.unit}`)
  },
  sanitization: {
    enabled: true, // default
    includeOriginalError: false, // default - excludes PII
    additionalSensitiveFields: ['internalId', 'taxId'],
  }
}

<GustoProvider
  config={{
    baseUrl: '/api/',
    observability,
  }}
  components={components}
>
  <YourApp />
</GustoProvider>

// Component names are automatically tracked
<Employee.Profile
  companyId={companyId}
  employeeId={employeeId}
  onEvent={handleEvent}
/>

Changes

• Added ObservabilityHook interface with onError and onMetric callbacks
• Implemented automatic PII sanitization (SSN, emails, phone numbers, credit cards, sensitive field names)
• Added error tracking for boundary errors, validation errors, API errors, and internal errors
• Added performance metrics for form submissions and component loading
• Components automatically report their names in error context and metrics for precise tracking
• Created comprehensive documentation with integration examples for Sentry, Datadog, and custom solutions

Related

• Jira: SDK-492

Testing

Manual Testing:

1. Configure observability hook in GustoProvider
2. Trigger errors (boundary, validation, API) and verify they're reported with component names
3. Submit forms and verify metrics are tracked
4. Test PII sanitization with sample data containing SSN, emails, etc.

Automated Tests:

npm run tsc                     # ✅ TypeScript compilation passes
npm run test -- --run           # ✅ All 130 test files pass (1438 tests)
npm run test -- --run src/contexts/ObservabilityProvider/sanitization.test.ts  # ✅ 20 PII sanitization tests

Test Results:

• TypeScript: ✅ No errors
• Tests: ✅ 1438 tests passing (including 20 new sanitization tests)
• Linting: ✅ No issues

Documentation:

• docs/integration-guide/observability.md - Complete guide
• docs/integration-guide/observability-examples.md - Integration examples

[Copilot]

Pull request overview

Adds an SDK-level observability hook (errors + performance metrics) intended for integration with external monitoring tools, with built-in PII sanitization before data leaves the SDK.

Changes:

• Introduces ObservabilityHook + related types, and wires an ObservabilityProvider into the provider tree.
• Adds PII sanitization utilities with tests, and a wrapper hook to sanitize data before invoking consumer callbacks.
• Emits observability events for error boundaries and form submit / suspense-loading durations, plus docs for usage/integrations.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
src/types/observability.ts	Defines public observability types and sanitization config.
src/index.ts	Exports observability types and createObservabilityError from package entrypoint.
src/contexts/index.ts	Re-exports observability context/provider APIs.
src/contexts/ObservabilityProvider/useSanitizedObservability.ts	Wraps callbacks to sanitize errors/metrics before dispatching.
src/contexts/ObservabilityProvider/useObservability.ts	Context hook returning a sanitized observability hook.
src/contexts/ObservabilityProvider/sanitization.ts	Implements recursive sanitization + PII redaction patterns.
src/contexts/ObservabilityProvider/sanitization.test.ts	Adds sanitization unit tests.
src/contexts/ObservabilityProvider/observabilityUtils.ts	Converts known SDK error classes into ObservabilityError.
src/contexts/ObservabilityProvider/index.ts	Public exports for the ObservabilityProvider module.
src/contexts/ObservabilityProvider/ObservabilityProvider.tsx	Context provider for passing consumer observability hook.
src/contexts/ObservabilityProvider/ObservabilityContext.ts	Creates observability React context value type.
src/contexts/GustoProvider/GustoProviderCustomUIAdapter.tsx	Wraps app with ObservabilityProvider and reports top-level boundary errors.
src/components/Contractor/Payments/CreatePayment/CreatePayment.tsx	Supplies a component name into BaseComponent for tagging.
src/components/Base/useBaseSubmit.ts	Emits observability errors + submit duration metrics on base submits.
src/components/Base/useBase.tsx	Extends BaseContext to include an optional component name.
src/components/Base/Base.tsx	Emits boundary errors + suspense loading-duration metrics, propagates component name.
docs/integration-guide/observability.md	Adds observability + sanitization documentation and integration guidance.
docs/integration-guide/observability-examples.md	Adds sample implementations (console/Sentry/Datadog/custom).
docs/integration-guide/error-handling.md	Links error handling docs to observability hooks.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.