@gusto/embedded-react-sdk 0.55.6 → 0.55.8

package/dist/types/sdkError.js

@@ -1,46 +1,47 @@
-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";
-const A = {
+import { APIError as n } from "@gusto/embedded-api/models/errors/apierror";
+import { GustoEmbeddedError as o } from "@gusto/embedded-api/models/errors/gustoembeddederror";
+import { HTTPClientError as i } from "@gusto/embedded-api/models/errors/httpclienterrors";
+import { SDKValidationError as c } from "@gusto/embedded-api/models/errors/sdkvalidationerror";
+import { getFieldErrors as g } from "../helpers/apiErrorToList.js";
+const S = {
   API_ERROR: "api_error",
   VALIDATION_ERROR: "validation_error",
   NETWORK_ERROR: "network_error",
   INTERNAL_ERROR: "internal_error"
-};
+}, f = "Something went wrong. Please try again.";
 class u extends Error {
   category;
   constructor(e, t = "internal_error") {
     super(e), this.name = "SDKInternalError", this.category = t;
   }
 }
-function f(r) {
+function m(r) {
   return r !== null && typeof r == "object" && "errors" in r && Array.isArray(r.errors);
 }
-function g(r) {
+function l(r) {
   if (!r) return r;
   const e = r.replace(/_/g, " ");
   return e.charAt(0).toUpperCase() + e.slice(1);
 }
-function m(r, e) {
+function E(r, e) {
   if (!r || !e) return r;
-  const t = g(e);
+  const t = l(e);
   return r.replace(e, t);
 }
-function a(r) {
+function s(r) {
   const e = r.message ?? "";
   return {
     field: r.errorKey,
-    message: m(e, r.errorKey),
+    message: E(e, r.errorKey),
     category: r.category,
     metadata: r.metadata
   };
 }
-function l(r) {
-  const e = r.flatMap((t) => c(t));
-  return e.length > 0 ? e.map(a) : r.filter((t) => t.message).map(a);
-}
 function p(r) {
+  const e = r.flatMap((t) => g(t));
+  return e.length > 0 ? e.map(s) : r.filter((t) => t.message).map(s);
+}
+function y(r) {
   return {
     errorKey: r.errorKey ?? r.error_key ?? "",
     category: r.category,
@@ -53,15 +54,15 @@ function d(r) {
   try {
     const e = JSON.parse(r);
     if (e !== null && typeof e == "object" && "errors" in e && Array.isArray(e.errors))
-      return e.errors.filter((s) => s.message).map(p).map(a);
+      return e.errors.filter((a) => a.message).map(y).map(s);
   } catch {
   }
   return [];
 }
-function y(r, e) {
+function _(r, e) {
   return r.length === 0 ? e : r.length === 1 ? "1 field has issues" : `${r.length} fields have issues`;
 }
-function K(r) {
+function M(r) {
   if (r instanceof u)
     return {
       category: r.category,
@@ -69,25 +70,25 @@ function K(r) {
       fieldErrors: [],
       raw: r
     };
-  if (r instanceof i)
+  if (r instanceof c)
     return {
       category: "validation_error",
       message: typeof r.rawMessage == "string" ? r.rawMessage : r.message,
       fieldErrors: [],
       raw: r
     };
-  if (r instanceof o)
+  if (r instanceof i)
     return {
       category: "network_error",
       message: r.message,
       fieldErrors: [],
       raw: r
     };
-  if (r instanceof n) {
-    const e = r.httpMeta.response.status, t = f(r) ? l(r.errors) : d(r.httpMeta.body);
+  if (r instanceof o) {
+    const e = r.httpMeta.response.status, t = m(r) ? p(r.errors) : d(r.httpMeta.body), a = r instanceof n ? f : r.message;
     return {
       category: "api_error",
-      message: y(t, r.message),
+      message: _(t, a),
       httpStatus: e,
       fieldErrors: t,
       raw: r
@@ -106,8 +107,9 @@ function K(r) {
   };
 }
 export {
-  A as SDKErrorCategories,
+  f as GENERIC_API_ERROR_MESSAGE,
+  S as SDKErrorCategories,
   u as SDKInternalError,
-  K as normalizeToSDKError
+  M as normalizeToSDKError
 };
 //# sourceMappingURL=sdkError.js.map

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 * 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":["SDKErrorCategories","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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"}
+{"version":3,"file":"sdkError.js","sources":["../../src/types/sdkError.ts"],"sourcesContent":["import type { EntityErrorObject } from '@gusto/embedded-api/models/components/entityerrorobject'\nimport { APIError } from '@gusto/embedded-api/models/errors/apierror'\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 * 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 * Fallback message used when an API error response carries no extractable field errors\n * (e.g. a non-JSON or unrecognized 5xx body) — never surfaces the raw response body.\n *\n * @internal\n */\nexport const GENERIC_API_ERROR_MESSAGE = 'Something went wrong. Please try again.'\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    const fallbackMessage = error instanceof APIError ? GENERIC_API_ERROR_MESSAGE : error.message\n\n    return {\n      category: 'api_error',\n      message: buildApiErrorMessage(fieldErrors, fallbackMessage),\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":["SDKErrorCategories","GENERIC_API_ERROR_MESSAGE","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","APIError"],"mappings":"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"}

package/docs/guides/endpoint-inventory.json

@@ -251,6 +251,11 @@
           "path": "/v1/companies/:companyId/bank_accounts",
           "docsUrl": "https://docs.gusto.com/embedded-payroll/v2026-06-15/reference/get-v1-companies-company_id-bank-accounts"
         },
+        {
+          "method": "GET",
+          "path": "/v1/companies/:companyId/employees",
+          "docsUrl": "https://docs.gusto.com/embedded-payroll/v2026-06-15/reference/get-v1-companies-company_id-employees"
+        },
         {
           "method": "GET",
           "path": "/v1/companies/:companyId/payrolls/:payrollId",
@@ -2509,6 +2514,13 @@
         "EmployeeOnboarding.OnboardingFlow"
       ]
     },
+    "ContractorManagement.ContractorListFlow": {
+      "blocks": [
+        "ContractorManagement.ContractorList",
+        "ContractorManagement.DashboardFlow",
+        "ContractorOnboarding.OnboardingFlow"
+      ]
+    },
     "ContractorManagement.CreatePaymentFlow": {
       "blocks": [
         "ContractorManagement.CreatePayment",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusto/embedded-react-sdk",
-  "version": "0.55.6",
+  "version": "0.55.8",
   "homepage": "https://github.com/Gusto/embedded-react-sdk",
   "bugs": {
     "url": "https://github.com/Gusto/embedded-react-sdk/issues"
@@ -88,6 +88,7 @@
     "sdk-app:demo": "npx tsx sdk-app/scripts/start.ts dev --env=demo",
     "sdk-app:staging": "npx tsx sdk-app/scripts/start.ts dev --env=staging",
     "sdk-app:local": "npx tsx sdk-app/scripts/start.ts dev --env=local",
+    "sdk-app:partner": "npx tsx sdk-app/scripts/start.ts dev --env=partner",
     "sdk-app-prod": "npx tsx sdk-app/scripts/start.ts prod --env=demo",
     "sdk-app:build": "vite build --config sdk-app/vite.config.ts",
     "sdk-app:setup": "npx tsx sdk-app/scripts/setup.ts",
@@ -98,32 +99,32 @@
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
     "@eslint/js": "^9.39.5",
-    "@microsoft/api-extractor": "^7.59.0",
-    "@playwright/test": "^1.62.1",
-    "@release-it/conventional-changelog": "^12.0.0",
-    "@storybook/addon-a11y": "^10.5.10",
-    "@storybook/addon-docs": "^10.5.10",
-    "@storybook/addon-onboarding": "^10.5.10",
-    "@storybook/react-vite": "^10.5.10",
-    "@storybook/test-runner": "^0.24.4",
-    "@testing-library/dom": "^10.4.1",
+    "@microsoft/api-extractor": "^7.59.1",
+    "@playwright/test": "^1.63.0",
+    "@release-it/conventional-changelog": "^12.0.2",
+    "@storybook/addon-a11y": "^10.6.0",
+    "@storybook/addon-docs": "^10.6.0",
+    "@storybook/addon-onboarding": "^10.6.0",
+    "@storybook/react-vite": "^10.6.0",
+    "@storybook/test-runner": "^0.24.5",
+    "@testing-library/dom": "^10.4.2",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",
-    "@testing-library/user-event": "^14.6.6",
+    "@testing-library/user-event": "^14.6.7",
     "@types/eslint-plugin-jsx-a11y": "^6.10.1",
     "@types/jest": "^30.0.0",
     "@types/jest-axe": "^3.5.9",
     "@types/pngjs": "^6.0.5",
     "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.5",
+    "@types/react-dom": "^19.3.0",
     "@typescript-eslint/parser": "^8.69.0",
-    "@typescript-eslint/rule-tester": "^8.68.0",
+    "@typescript-eslint/rule-tester": "^8.70.0",
     "@typescript-eslint/utils": "^8.68.0",
     "@vitejs/plugin-react-swc": "^4.3.3",
-    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/coverage-v8": "^5.0.0",
     "ajv": "^8.20.0",
     "axe-core": "^4.13.0",
-    "cspell": "^10.1.0",
+    "cspell": "^10.3.1",
     "dotenv": "^17.4.2",
     "eslint": "^9.39.5",
     "eslint-plugin-import": "^2.31.0",
@@ -131,16 +132,16 @@
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-react-refresh": "^0.4.24",
-    "eslint-plugin-storybook": "^10.5.10",
+    "eslint-plugin-storybook": "^10.6.0",
     "eslint-plugin-tsdoc": "^0.5.2",
     "fuse.js": "^7.5.0",
-    "globals": "^17.11.0",
+    "globals": "^17.12.0",
     "husky": "^9.1.7",
     "jest-axe": "^11.0.0",
     "jsdom": "^26.1.0",
     "jsdom-testing-mocks": "^1.16.0",
     "json-schema-to-typescript": "^16.0.0",
-    "lint-staged": "^17.4.1",
+    "lint-staged": "^17.5.1",
     "markdownlint-cli2": "^0.23.2",
     "msw": "^2.15.0",
     "npm-run-all": "^4.1.5",
@@ -151,22 +152,22 @@
     "react-dnd": "^16.0.1",
     "react-dnd-html5-backend": "^16.0.1",
     "react-router-dom": "^7.18.3",
-    "release-it": "^21.0.2",
-    "sass-embedded": "^1.103.1",
+    "release-it": "^21.0.3",
+    "sass-embedded": "^1.104.1",
     "storybook": "^10.5.5",
     "stylelint-config-standard": "^40.0.0",
     "ts-morph": "^28.0.0",
     "tsx": "^4.23.13",
-    "typescript-eslint": "^8.69.0",
+    "typescript-eslint": "^8.70.0",
     "vite": "^6.4.3",
     "vite-plugin-checker": "^0.14.5",
     "vite-plugin-circular-dependency": "^0.6.0",
-    "vite-plugin-dts": "^4.5.3",
+    "vite-plugin-dts": "^5.1.0",
     "vite-plugin-externalize-deps": "^0.10.0",
     "vite-plugin-stylelint": "^6.3.0",
     "vite-plugin-svgr": "^5.2.0",
-    "vitest": "^4.1.10",
-    "yaml": "^2.9.0"
+    "vitest": "^5.0.0",
+    "yaml": "^2.9.1"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5",
@@ -176,7 +177,7 @@
   },
   "overrides": {
     "esbuild": "^0.28.1",
-    "js-yaml": "^4.2.0",
+    "js-yaml": "^4.3.2",
     "uuid": "^11.1.1",
     "@babel/core": "^7.29.6",
     "markdown-it": "^14.2.0",
@@ -187,17 +188,17 @@
     "@gusto/embedded-api": "npm:@gusto/embedded-api-v-2026-06-15@0.3.0-rc.2",
     "@hookform/error-message": "^2.0.1",
     "@hookform/resolvers": "^5.9.1",
-    "@internationalized/date": "^3.12.3",
-    "@internationalized/number": "^3.6.7",
+    "@internationalized/date": "^3.12.4",
+    "@internationalized/number": "^3.6.8",
     "classnames": "^2.5.1",
     "deepmerge": "^4.3.1",
-    "dompurify": "^3.4.14",
-    "i18next": "^26.4.0",
+    "dompurify": "^3.4.15",
+    "i18next": "^26.4.2",
     "react-aria": "^3.47.0",
     "react-aria-components": "1.16.0",
     "react-error-boundary": "^6.1.5",
-    "react-hook-form": "^7.87.0",
-    "react-i18next": "^17.0.12",
+    "react-hook-form": "^7.88.0",
+    "react-i18next": "^17.0.14",
     "react-robot": "^1.2.1",
     "robot3": "^1.2.0",
     "zod": "^4.3.6"

package/dist/components/Common/FieldCaption/index.d.ts

@@ -1 +0,0 @@
-export { FieldCaption } from './FieldCaption';

package/dist/components/Contractor/Submit/SubmitDone.d.ts

@@ -1,6 +0,0 @@
-interface SubmitDoneProps {
-    onDone: () => void;
-}
-/** @internal */
-export declare const SubmitDone: ({ onDone }: SubmitDoneProps) => import("react").JSX.Element;
-export {};

package/dist/components/Payroll/OffCycleCreation/OffCycleCreationPresentation.d.ts

@@ -1,3 +0,0 @@
-import { OffCycleCreationPresentationProps } from './OffCycleCreationTypes';
-/** @internal */
-export declare function OffCycleCreationPresentation({ employees, isPending, minCheckDate, minCheckOnlyDate, taxWithholdingConfig, isTaxWithholdingModalOpen, onTaxWithholdingEditClick, onTaxWithholdingModalDone, onTaxWithholdingModalCancel, }: OffCycleCreationPresentationProps): import("react").JSX.Element;

package/dist/components/Payroll/TransitionCreation/TransitionCreationPresentation.d.ts

@@ -1,9 +0,0 @@
-import { TransitionCreationPresentationProps } from './TransitionCreationTypes';
-/**
- * Presentational layout for the transition payroll creation form.
- *
- * @param props - {@link TransitionCreationPresentationProps}.
- * @returns The transition payroll creation form layout.
- * @internal
- */
-export declare function TransitionCreationPresentation({ startDate, endDate, payScheduleName, isPending, taxWithholdingConfig, isTaxWithholdingModalOpen, onTaxWithholdingEditClick, onTaxWithholdingModalDone, onTaxWithholdingModalCancel, }: TransitionCreationPresentationProps): import("react").JSX.Element;

package/dist/components/Payroll/UNSTABLE_PayrollEditEmployee/UNSTABLE_PayrollEditEmployee.d.ts

@@ -1,13 +0,0 @@
-import { PayrollEditEmployeeProps } from '../PayrollEditEmployee/PayrollEditEmployee';
-/**
- * In-development regular-rate-of-pay rebuild of {@link PayrollEditEmployee}.
- *
- * @remarks
- * Gated behind the `payrollRegularRateOfPay` unstable feature flag and not part of the public
- * SDK surface. `PayrollEditEmployee` renders this in place of the stable editor when the flag is
- * enabled. Currently a scaffold: the header, `Cancel`, and `Save` controls only. `Cancel` and
- * `Save` emit the same events as the stable component so the surrounding flow behaves identically.
- *
- * @internal
- */
-export declare function UNSTABLE_PayrollEditEmployee(props: PayrollEditEmployeeProps): import("react").JSX.Element;