@gusto/embedded-react-sdk 0.46.2 → 0.47.0

package/dist/types/observability.d.ts

@@ -1,14 +1,20 @@
 import { SDKError } from './sdkError';
+/**
+ * Unit of measure for an {@link ObservabilityMetric}.
+ *
+ * @public
+ */
 export type ObservabilityMetricUnit = 'ms' | 'count' | 'bytes' | 'percent';
 /**
- * An `SDKError` enriched with internal component context for observability telemetry.
+ * An {@link SDKError} enriched with 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.
+ * @remarks
+ * Delivered to {@link ObservabilityHook.onError}. Extends {@link SDKError} with
+ * `timestamp`, `componentName`, and `componentStack` so error-tracking tools
+ * (e.g. Sentry) can correlate and group errors. The base {@link SDKError}
+ * (without these fields) is the shape exposed through form hooks.
  *
- * The base `SDKError` (without these fields) is the type used in partner-facing
- * hooks like `useEmployeeForm`, keeping the public API clean.
+ * @public
  */
 export interface ObservabilityError extends SDKError {
     /** When the error occurred (Unix timestamp in milliseconds) */
@@ -18,6 +24,16 @@ export interface ObservabilityError extends SDKError {
     /** React component stack trace (present only for errors caught by ErrorBoundary) */
     componentStack?: string;
 }
+/**
+ * A performance metric emitted by the SDK to {@link ObservabilityHook.onMetric}.
+ *
+ * @remarks
+ * Built-in metric names include `sdk.form.submit_duration` (form submission time)
+ * and `sdk.component.loading_duration` (time spent in loading/suspense state).
+ * Tags may include `status` (`success` or `error`) and `component` when known.
+ *
+ * @public
+ */
 export interface ObservabilityMetric {
     /** Metric name (e.g., 'sdk.form.submit_duration', 'sdk.component.loading_duration') */
     name: string;
@@ -31,7 +47,16 @@ export interface ObservabilityMetric {
     timestamp: number;
 }
 /**
- * Configuration for data sanitization in observability hooks
+ * Configuration for sanitizing error and metric data before it reaches observability hooks.
+ *
+ * @remarks
+ * Sanitization runs by default to prevent PII leakage. When enabled, the SDK
+ * pattern-redacts SSNs, emails, phone numbers, credit card numbers, and API
+ * tokens from messages and tags, and removes values for fields with sensitive
+ * names (`password`, `ssn`, `bankAccount`, etc.) from metadata. The `raw`
+ * error object is excluded unless `includeRawError` is set to `true`.
+ *
+ * @public
  */
 export interface SanitizationConfig {
     /**
@@ -57,37 +82,38 @@ export interface SanitizationConfig {
     additionalSensitiveFields?: string[];
 }
 /**
- * Observability hook interface for SDK consumers to implement
+ * Hooks for routing SDK errors and performance metrics into an external monitoring tool.
+ *
+ * @remarks
+ * Pass an instance to {@link GustoProvider} via `config.observability` to forward
+ * errors to services like Sentry or Datadog and to capture performance metrics
+ * for form submissions and component loading. Sanitization is applied before
+ * the hooks are invoked; see {@link SanitizationConfig}.
+ *
+ * @public
  *
  * @example
  * ```tsx
  * import * as Sentry from '@sentry/react'
- * import { GustoProvider } from '@gusto/embedded-react-sdk'
+ * import { GustoProvider, type ObservabilityHook } from '@gusto/embedded-react-sdk'
  *
- * <GustoProvider
- *   config={{
- *     baseUrl: '/api/',
- *     observability: {
- *       onError: (error: ObservabilityError) => {
- *         Sentry.captureException(error.raw, {
- *           level: error.category === 'validation_error' ? 'warning' : 'error',
- *           tags: {
- *             error_category: error.category,
- *             component: error.componentName ?? 'unknown',
- *             http_status: String(error.httpStatus ?? ''),
- *           },
- *         })
- *       },
- *       onMetric: (metric) => {
- *         console.log(`[Metric] ${metric.name}: ${metric.value}${metric.unit}`)
+ * const observability: ObservabilityHook = {
+ *   onError: error => {
+ *     Sentry.captureException(error.raw ?? new Error(error.message), {
+ *       level: error.category === 'validation_error' ? 'warning' : 'error',
+ *       tags: {
+ *         error_category: error.category,
+ *         component: error.componentName ?? 'unknown',
+ *         http_status: String(error.httpStatus ?? ''),
  *       },
- *       sanitization: {
- *         enabled: true,
- *         includeRawError: false,
- *       }
- *     }
- *   }}
- * >
+ *     })
+ *   },
+ *   onMetric: metric => {
+ *     console.log(`[Metric] ${metric.name}: ${metric.value}${metric.unit ?? ''}`)
+ *   },
+ * }
+ *
+ * <GustoProvider config={{ baseUrl: '/api/', observability }}>
  *   <YourApp />
  * </GustoProvider>
  * ```
@@ -105,7 +131,7 @@ export interface ObservabilityHook {
     onMetric?: (metric: ObservabilityMetric) => void;
     /**
      * Configuration for sanitizing data before sending to observability tools.
-     * Default: { enabled: true, includeRawError: false }
+     * Default: `{ enabled: true, includeRawError: false }`
      */
     sanitization?: SanitizationConfig;
 }

package/dist/types/sdkError.d.ts

@@ -1,10 +1,18 @@
 /**
- * High-level classification of where/how the error originated.
+ * Constant map of {@link SDKErrorCategory} string values keyed by uppercase name.
  *
- * - `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)
+ * @remarks
+ * Use this when you need to reference a category value by name (e.g.
+ * `SDKErrorCategories.API_ERROR`). Each entry corresponds to one classification:
+ *
+ * | Value | When it applies |
+ * | ----- | --------------- |
+ * | `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) |
+ *
+ * @public
  */
 export declare const SDKErrorCategories: {
     readonly API_ERROR: "api_error";
@@ -12,6 +20,11 @@ export declare const SDKErrorCategories: {
     readonly NETWORK_ERROR: "network_error";
     readonly INTERNAL_ERROR: "internal_error";
 };
+/**
+ * High-level classification of where an {@link SDKError} originated.
+ *
+ * @public
+ */
 export type SDKErrorCategory = (typeof SDKErrorCategories)[keyof typeof SDKErrorCategories];
 /**
  * An error thrown by internal SDK logic that should be caught and normalized
@@ -20,6 +33,8 @@ export type SDKErrorCategory = (typeof SDKErrorCategories)[keyof typeof SDKError
  * 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.
  *
+ * @internal
+ *
  * @example
  * ```typescript
  * await baseSubmitHandler(data, async () => {
@@ -37,9 +52,13 @@ export declare class SDKInternalError extends Error {
 /**
  * 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"`).
+ * @remarks
+ * For API errors with structured field errors (e.g. 422 responses), nested
+ * `errors[]` structures are recursively flattened into one entry per leaf
+ * field. The `field` property is the dot-separated camelCase path
+ * (e.g. `"firstName"`, `"states.CA.filingStatus.value"`).
+ *
+ * @public
  */
 export interface SDKFieldError {
     /** Dot-separated camelCase field path (e.g. "firstName", "states.CA.filingStatus.value") */
@@ -52,15 +71,26 @@ export interface SDKFieldError {
     metadata?: Record<string, unknown>;
 }
 /**
- * The unified SDK error type for all error scenarios.
+ * Unified error shape returned by every form hook and error-handling surface.
+ *
+ * @remarks
+ * Every caught error — whether from the Gusto API, client-side Zod validation,
+ * a network failure, or an unexpected runtime exception — is normalized into
+ * this shape. The {@link SDKErrorCategory} `category` field distinguishes
+ * which source produced the error; `fieldErrors` is populated for structured
+ * API responses (typically 422) and is an empty array otherwise.
+ *
+ * Observability telemetry uses {@link ObservabilityError}, which extends this
+ * shape with component context.
  *
- * This is the core error shape exposed through partner-facing hooks. For
- * observability telemetry (which includes component context), see
- * `ObservabilityError` in `@/types/observability`.
+ * @public
  *
  * @example
  * ```tsx
- * const { error } = useEmployeeForm({ employeeId })
+ * import { useEmployeeForm } from '@gusto/embedded-react-sdk'
+ *
+ * const { errorHandling } = useEmployeeForm({ employeeId })
+ * const error = errorHandling.error
  *
  * if (error) {
  *   console.log(error.category)    // 'api_error'
@@ -93,5 +123,7 @@ export interface SDKError {
  * - `SDKValidationError` → `validation_error`
  * - `HTTPClientError` subclasses → `network_error`
  * - Everything else → `internal_error`
+ *
+ * @internal
  */
 export declare function normalizeToSDKError(error: unknown): SDKError;

package/dist/types/sdkError.js

@@ -1,6 +1,6 @@
-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 { GustoEmbeddedError as n } from "@gusto/embedded-api-v-2025-11-15/models/errors/gustoembeddederror";
+import { HTTPClientError as o } from "@gusto/embedded-api-v-2025-11-15/models/errors/httpclienterrors";
+import { SDKValidationError as i } from "@gusto/embedded-api-v-2025-11-15/models/errors/sdkvalidationerror";
 import { getFieldErrors as c } from "../helpers/apiErrorToList.js";
 class u extends Error {
   category;

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 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 { errors: unknown }).errors)\n  )\n}\n\nfunction humanizeFieldName(snakeCaseField: string): string {\n  if (!snakeCaseField) return snakeCaseField\n  const words = snakeCaseField.replace(/_/g, ' ')\n  return words.charAt(0).toUpperCase() + words.slice(1)\n}\n\nfunction humanizeMessage(message: string, field: string): string {\n  if (!message || !field) return message\n  const humanized = humanizeFieldName(field)\n  return message.replace(field, humanized)\n}\n\nfunction toSDKFieldError(entityError: EntityErrorObject): SDKFieldError {\n  const rawMessage = entityError.message ?? ''\n  return {\n    field: entityError.errorKey,\n    message: humanizeMessage(rawMessage, entityError.errorKey),\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","humanizeFieldName","snakeCaseField","words","humanizeMessage","field","humanized","toSDKFieldError","entityError","rawMessage","extractFieldErrors","errors","flattened","err","getFieldErrors","rawToEntityError","raw","tryExtractFieldErrorsFromBody","body","parsed","buildApiErrorMessage","fieldErrors","fallbackMessage","normalizeToSDKError","SDKValidationError","HTTPClientError","GustoEmbeddedError","httpStatus"],"mappings":";;;;AAwCO,MAAMA,UAAyB,MAAM;AAAA,EACjC;AAAA,EAET,YAAYC,GAAiBC,IAA6B,kBAAkB;AAC1E,UAAMD,CAAO,GACb,KAAK,OAAO,oBACZ,KAAK,WAAWC;AAAA,EAClB;AACF;AA8DA,SAASC,EAAeC,GAA0C;AAChE,SACEA,MAAU,QACV,OAAOA,KAAU,YACjB,YAAYA,KACZ,MAAM,QAASA,EAA8B,MAAM;AAEvD;AAEA,SAASC,EAAkBC,GAAgC;AACzD,MAAI,CAACA,EAAgB,QAAOA;AAC5B,QAAMC,IAAQD,EAAe,QAAQ,MAAM,GAAG;AAC9C,SAAOC,EAAM,OAAO,CAAC,EAAE,gBAAgBA,EAAM,MAAM,CAAC;AACtD;AAEA,SAASC,EAAgBP,GAAiBQ,GAAuB;AAC/D,MAAI,CAACR,KAAW,CAACQ,EAAO,QAAOR;AAC/B,QAAMS,IAAYL,EAAkBI,CAAK;AACzC,SAAOR,EAAQ,QAAQQ,GAAOC,CAAS;AACzC;AAEA,SAASC,EAAgBC,GAA+C;AACtE,QAAMC,IAAaD,EAAY,WAAW;AAC1C,SAAO;AAAA,IACL,OAAOA,EAAY;AAAA,IACnB,SAASJ,EAAgBK,GAAYD,EAAY,QAAQ;AAAA,IACzD,UAAUA,EAAY;AAAA,IACtB,UAAUA,EAAY;AAAA,EAAA;AAE1B;AAQA,SAASE,EAAmBC,GAA8C;AACxE,QAAMC,IAAYD,EAAO,QAAQ,CAAAE,MAAOC,EAAeD,CAAG,CAAC;AAC3D,SAAID,EAAU,SAAS,IACdA,EAAU,IAAIL,CAAe,IAG/BI,EAAO,OAAO,CAAAE,MAAOA,EAAI,OAAO,EAAE,IAAIN,CAAe;AAC9D;AAUA,SAASQ,EAAiBC,GAA0C;AAClE,SAAO;AAAA,IACL,UAAUA,EAAI,YAAYA,EAAI,aAAa;AAAA,IAC3C,UAAUA,EAAI;AAAA,IACd,SAASA,EAAI;AAAA,IACb,UAAUA,EAAI;AAAA,EAAA;AAElB;AAEA,SAASC,EAA8BC,GAA2C;AAChF,MAAI,CAACA,EAAM,QAAO,CAAA;AAClB,MAAI;AACF,UAAMC,IAAkB,KAAK,MAAMD,CAAI;AACvC,QACEC,MAAW,QACX,OAAOA,KAAW,YAClB,YAAYA,KACZ,MAAM,QAASA,EAA+B,MAAM;AAGpD,aADgBA,EAA0C,OAEvD,OAAO,CAAAN,MAAOA,EAAI,OAAO,EACzB,IAAIE,CAAgB,EACpB,IAAIR,CAAe;AAAA,EAE1B,QAAQ;AAAA,EAER;AACA,SAAO,CAAA;AACT;AAEA,SAASa,EAAqBC,GAA8BC,GAAiC;AAC3F,SAAID,EAAY,WAAW,IAClBC,IAEFD,EAAY,WAAW,IAC1B,uBACA,GAAGA,EAAY,MAAM;AAC3B;AAYO,SAASE,EAAoBvB,GAA0B;AAC5D,MAAIA,aAAiBJ;AACnB,WAAO;AAAA,MACL,UAAUI,EAAM;AAAA,MAChB,SAASA,EAAM;AAAA,MACf,aAAa,CAAA;AAAA,MACb,KAAKA;AAAA,IAAA;AAIT,MAAIA,aAAiBwB;AACnB,WAAO;AAAA,MACL,UAAU;AAAA,MACV,SAAS,OAAOxB,EAAM,cAAe,WAAWA,EAAM,aAAaA,EAAM;AAAA,MACzE,aAAa,CAAA;AAAA,MACb,KAAKA;AAAA,IAAA;AAIT,MAAIA,aAAiByB;AACnB,WAAO;AAAA,MACL,UAAU;AAAA,MACV,SAASzB,EAAM;AAAA,MACf,aAAa,CAAA;AAAA,MACb,KAAKA;AAAA,IAAA;AAIT,MAAIA,aAAiB0B,GAAoB;AACvC,UAAMC,IAAa3B,EAAM,SAAS,SAAS,QACrCqB,IAActB,EAAeC,CAAK,IACpCU,EAAmBV,EAAM,MAAM,IAC/BiB,EAA8BjB,EAAM,SAAS,IAAI;AAErD,WAAO;AAAA,MACL,UAAU;AAAA,MACV,SAASoB,EAAqBC,GAAarB,EAAM,OAAO;AAAA,MACxD,YAAA2B;AAAA,MACA,aAAAN;AAAA,MACA,KAAKrB;AAAA,IAAA;AAAA,EAET;AAEA,SAAIA,aAAiB,QACZ;AAAA,IACL,UAAU;AAAA,IACV,SAASA,EAAM;AAAA,IACf,aAAa,CAAA;AAAA,IACb,KAAKA;AAAA,EAAA,IAIF;AAAA,IACL,UAAU;AAAA,IACV,SAAS;AAAA,IACT,aAAa,CAAA;AAAA,IACb,KAAKA;AAAA,EAAA;AAET;"}
+{"version":3,"file":"sdkError.js","sources":["../../src/types/sdkError.ts"],"sourcesContent":["import type { EntityErrorObject } from '@gusto/embedded-api-v-2025-11-15/models/components/entityerrorobject'\nimport { GustoEmbeddedError } from '@gusto/embedded-api-v-2025-11-15/models/errors/gustoembeddederror'\nimport { HTTPClientError } from '@gusto/embedded-api-v-2025-11-15/models/errors/httpclienterrors'\nimport { SDKValidationError } from '@gusto/embedded-api-v-2025-11-15/models/errors/sdkvalidationerror'\nimport { getFieldErrors } from '@/helpers/apiErrorToList'\n\n/**\n * Constant map of {@link SDKErrorCategory} string values keyed by uppercase name.\n *\n * @remarks\n * Use this when you need to reference a category value by name (e.g.\n * `SDKErrorCategories.API_ERROR`). Each entry corresponds to one classification:\n *\n * | Value | When it applies |\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 *\n * @public\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\n/**\n * High-level classification of where an {@link SDKError} originated.\n *\n * @public\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 * @internal\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 * @remarks\n * For API errors with structured field errors (e.g. 422 responses), nested\n * `errors[]` structures are recursively flattened into one entry per leaf\n * field. The `field` property is the dot-separated camelCase path\n * (e.g. `\"firstName\"`, `\"states.CA.filingStatus.value\"`).\n *\n * @public\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 * Unified error shape returned by every form hook and error-handling surface.\n *\n * @remarks\n * Every caught error — whether from the Gusto API, client-side Zod validation,\n * a network failure, or an unexpected runtime exception — is normalized into\n * this shape. The {@link SDKErrorCategory} `category` field distinguishes\n * which source produced the error; `fieldErrors` is populated for structured\n * API responses (typically 422) and is an empty array otherwise.\n *\n * Observability telemetry uses {@link ObservabilityError}, which extends this\n * shape with component context.\n *\n * @public\n *\n * @example\n * ```tsx\n * import { useEmployeeForm } from '@gusto/embedded-react-sdk'\n *\n * const { errorHandling } = useEmployeeForm({ employeeId })\n * const error = errorHandling.error\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 { errors: unknown }).errors)\n  )\n}\n\nfunction humanizeFieldName(snakeCaseField: string): string {\n  if (!snakeCaseField) return snakeCaseField\n  const words = snakeCaseField.replace(/_/g, ' ')\n  return words.charAt(0).toUpperCase() + words.slice(1)\n}\n\nfunction humanizeMessage(message: string, field: string): string {\n  if (!message || !field) return message\n  const humanized = humanizeFieldName(field)\n  return message.replace(field, humanized)\n}\n\nfunction toSDKFieldError(entityError: EntityErrorObject): SDKFieldError {\n  const rawMessage = entityError.message ?? ''\n  return {\n    field: entityError.errorKey,\n    message: humanizeMessage(rawMessage, entityError.errorKey),\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 *\n * @internal\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","humanizeFieldName","snakeCaseField","words","humanizeMessage","field","humanized","toSDKFieldError","entityError","rawMessage","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

@@ -653,6 +653,10 @@
           "method": "PUT",
           "path": "/v1/compensations/:compensationId"
         },
+        {
+          "method": "DELETE",
+          "path": "/v1/compensations/:compensationId"
+        },
         {
           "method": "GET",
           "path": "/v1/employees/:employeeId"
@@ -821,57 +825,13 @@
     },
     "Employee.DashboardFlow": {
       "endpoints": [
-        {
-          "method": "DELETE",
-          "path": "/v1/compensations/:compensationId"
-        },
         {
           "method": "GET",
           "path": "/v1/employees/:employeeId"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/employees/:employeeId/forms"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/employees/:employeeId/home_addresses"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/employees/:employeeId/jobs"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/employees/:employeeId/pay_stubs"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/employees/:employeeId/work_addresses"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/employees/:employeeUuid/federal_taxes"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/employees/:employeeUuid/state_taxes"
-        },
-        {
-          "method": "DELETE",
-          "path": "/v1/jobs/:jobId"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/payrolls/:payrollId/employees/:employeeId/pay_stub"
         }
       ],
       "variables": [
-        "compensationId",
-        "employeeId",
-        "employeeUuid",
-        "jobId",
-        "payrollId"
+        "employeeId"
       ]
     },
     "Employee.HomeAddress": {
@@ -1184,6 +1144,10 @@
     },
     "Payroll.PayrollList": {
       "endpoints": [
+        {
+          "method": "GET",
+          "path": "/v1/companies/:companyId/pay_periods"
+        },
         {
           "method": "GET",
           "path": "/v1/companies/:companyId/pay_schedules"
@@ -1825,6 +1789,10 @@
           "method": "PUT",
           "path": "/v1/compensations/:compensationId"
         },
+        {
+          "method": "DELETE",
+          "path": "/v1/compensations/:compensationId"
+        },
         {
           "method": "GET",
           "path": "/v1/employees/:employeeId"
@@ -1948,19 +1916,19 @@
         "employeeId"
       ]
     },
-    "EmployeeManagement.DocumentManager": {
+    "EmployeeManagement.Documents": {
       "endpoints": [
         {
           "method": "GET",
-          "path": "/v1/employees/:employeeId/forms/:formId"
+          "path": "/v1/employees/:employeeId/forms"
         },
         {
           "method": "GET",
-          "path": "/v1/employees/:employeeId/forms/:formId/pdf"
+          "path": "/v1/employees/:employeeId/forms/:formId"
         },
         {
-          "method": "PUT",
-          "path": "/v1/employees/:employeeId/forms/:formId/sign"
+          "method": "GET",
+          "path": "/v1/employees/:employeeId/forms/:formId/pdf"
         }
       ],
       "variables": [
@@ -1970,57 +1938,33 @@
     },
     "EmployeeManagement.DashboardFlow": {
       "endpoints": [
-        {
-          "method": "DELETE",
-          "path": "/v1/compensations/:compensationId"
-        },
         {
           "method": "GET",
           "path": "/v1/employees/:employeeId"
-        },
+        }
+      ],
+      "variables": [
+        "employeeId"
+      ]
+    },
+    "EmployeeManagement.HomeAddress": {
+      "endpoints": [
         {
           "method": "GET",
-          "path": "/v1/employees/:employeeId/forms"
+          "path": "/v1/employees/:employeeId"
         },
         {
           "method": "GET",
           "path": "/v1/employees/:employeeId/home_addresses"
         },
-        {
-          "method": "GET",
-          "path": "/v1/employees/:employeeId/jobs"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/employees/:employeeId/pay_stubs"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/employees/:employeeId/work_addresses"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/employees/:employeeUuid/federal_taxes"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/employees/:employeeUuid/state_taxes"
-        },
         {
           "method": "DELETE",
-          "path": "/v1/jobs/:jobId"
-        },
-        {
-          "method": "GET",
-          "path": "/v1/payrolls/:payrollId/employees/:employeeId/pay_stub"
+          "path": "/v1/home_addresses/:homeAddressUuid"
         }
       ],
       "variables": [
-        "compensationId",
         "employeeId",
-        "employeeUuid",
-        "jobId",
-        "payrollId"
+        "homeAddressUuid"
       ]
     },
     "EmployeeManagement.WorkAddress": {
@@ -2067,6 +2011,38 @@
         "employeeId"
       ]
     },
+    "EmployeeManagement.PaystubsCard": {
+      "endpoints": [
+        {
+          "method": "GET",
+          "path": "/v1/employees/:employeeId/pay_stubs"
+        },
+        {
+          "method": "GET",
+          "path": "/v1/payrolls/:payrollId/employees/:employeeId/pay_stub"
+        }
+      ],
+      "variables": [
+        "employeeId",
+        "payrollId"
+      ]
+    },
+    "EmployeeManagement.Compensation": {
+      "endpoints": [
+        {
+          "method": "GET",
+          "path": "/v1/employees/:employeeId/jobs"
+        },
+        {
+          "method": "DELETE",
+          "path": "/v1/jobs/:jobId"
+        }
+      ],
+      "variables": [
+        "employeeId",
+        "jobId"
+      ]
+    },
     "EmployeeManagement.TerminateEmployee": {
       "endpoints": [
         {
@@ -2601,32 +2577,31 @@
     },
     "Employee.DashboardFlow": {
       "blocks": [
-        "Employee.Compensation",
-        "Employee.Deductions",
         "Employee.HomeAddress",
-        "Employee.PaymentMethod",
         "Employee.WorkAddress",
-        "EmployeeManagement.DocumentManager",
+        "EmployeeManagement.Compensation",
+        "EmployeeManagement.Deductions",
+        "EmployeeManagement.Documents",
         "EmployeeManagement.FederalTaxes",
+        "EmployeeManagement.PaymentMethod",
+        "EmployeeManagement.PaystubsCard",
         "EmployeeManagement.Profile",
-        "EmployeeManagement.StateTaxes",
-        "EmployeeOnboarding.PaymentMethod"
+        "EmployeeManagement.StateTaxes"
       ]
     },
     "Employee.EmployeeListFlow": {
       "blocks": [
         "Employee.DashboardFlow",
-        "Employee.OnboardingFlow",
+        "Employee.OnboardingExecutionFlow",
         "Employee.TerminationFlow",
         "EmployeeManagement.EmployeeList"
       ]
     },
-    "Employee.OnboardingFlow": {
+    "Employee.OnboardingExecutionFlow": {
       "blocks": [
         "Employee.Compensation",
         "Employee.Deductions",
         "Employee.EmployeeDocuments",
-        "Employee.EmployeeList",
         "Employee.OnboardingSummary",
         "Employee.PaymentMethod",
         "Employee.Profile",
@@ -2634,6 +2609,12 @@
         "EmployeeOnboarding.StateTaxes"
       ]
     },
+    "Employee.OnboardingFlow": {
+      "blocks": [
+        "Employee.EmployeeList",
+        "Employee.OnboardingExecutionFlow"
+      ]
+    },
     "Employee.SelfOnboardingFlow": {
       "blocks": [
         "Employee.DocumentSigner",
@@ -2655,16 +2636,16 @@
     },
     "EmployeeManagement.DashboardFlow": {
       "blocks": [
-        "Employee.HomeAddress",
-        "Employee.PaymentMethod",
-        "EmployeeManagement.DocumentManager",
+        "EmployeeManagement.Compensation",
+        "EmployeeManagement.Deductions",
+        "EmployeeManagement.Documents",
         "EmployeeManagement.FederalTaxes",
+        "EmployeeManagement.HomeAddress",
+        "EmployeeManagement.PaymentMethod",
+        "EmployeeManagement.PaystubsCard",
         "EmployeeManagement.Profile",
         "EmployeeManagement.StateTaxes",
-        "EmployeeManagement.WorkAddress",
-        "EmployeeOnboarding.Compensation",
-        "EmployeeOnboarding.Deductions",
-        "EmployeeOnboarding.PaymentMethod"
+        "EmployeeManagement.WorkAddress"
       ]
     },
     "EmployeeManagement.EmployeeListFlow": {
@@ -2672,7 +2653,7 @@
         "EmployeeManagement.DashboardFlow",
         "EmployeeManagement.EmployeeList",
         "EmployeeManagement.TerminationFlow",
-        "EmployeeOnboarding.OnboardingFlow"
+        "EmployeeOnboarding.OnboardingExecutionFlow"
       ]
     },
     "EmployeeManagement.TerminationFlow": {
@@ -2683,19 +2664,24 @@
         "Payroll.PayrollLanding"
       ]
     },
-    "EmployeeOnboarding.OnboardingFlow": {
+    "EmployeeOnboarding.OnboardingExecutionFlow": {
       "blocks": [
         "Employee.EmployeeDocuments",
         "Employee.PaymentMethod",
         "EmployeeOnboarding.Compensation",
         "EmployeeOnboarding.Deductions",
-        "EmployeeOnboarding.EmployeeList",
         "EmployeeOnboarding.FederalTaxes",
         "EmployeeOnboarding.OnboardingSummary",
         "EmployeeOnboarding.Profile",
         "EmployeeOnboarding.StateTaxes"
       ]
     },
+    "EmployeeOnboarding.OnboardingFlow": {
+      "blocks": [
+        "EmployeeOnboarding.EmployeeList",
+        "EmployeeOnboarding.OnboardingExecutionFlow"
+      ]
+    },
     "EmployeeOnboarding.SelfOnboardingFlow": {
       "blocks": [
         "Employee.PaymentMethod",