@gusto/embedded-react-sdk 0.56.7 → 0.57.1

package/dist/src/components/Company/TaxPayments/TaxPaymentsList/TaxPaymentsList.d.ts

@@ -0,0 +1,28 @@
+import { BaseComponentInterface } from '../../../Base';
+/**
+ * Props for {@link TaxPaymentsList}.
+ *
+ * @alpha
+ */
+export interface TaxPaymentsListProps extends BaseComponentInterface<'Company.Management.TaxPaymentsList'> {
+    /** Identifier of the company whose tax payments are listed. */
+    companyId: string;
+}
+/**
+ * Lists a company's tax payments with search, jurisdiction and status filters, and an alert for
+ * overdue payments.
+ *
+ * @remarks
+ * Requires the `taxPayments` flag in {@link UnstableFeatures}. Status is derived from each
+ * payment's amounts and dates: `Paid`, `Scheduled`, `Overdue`, or `Refund / Credit`.
+ *
+ * @events
+ * | Event | Description | Data |
+ * | ----- | ----------- | ---- |
+ * | `company/taxPayments/view` | Fired when the user selects a tax payment to view | `{ taxPaymentId: string }` |
+ *
+ * @param props - See {@link TaxPaymentsListProps}.
+ * @returns The rendered tax payments list.
+ * @alpha
+ */
+export declare function TaxPaymentsList(props: TaxPaymentsListProps): import('react').JSX.Element;

package/dist/src/components/Company/TaxPayments/TaxPaymentsList/TaxPaymentsListPresentation.d.ts

@@ -0,0 +1,33 @@
+import { TaxPayment } from '@gusto/embedded-api/models/components/taxpayment';
+import { TaxPaymentStatus } from '../shared/taxPaymentStatus';
+import { PaginationControlProps } from '../../../Common/PaginationControl/PaginationControlTypes';
+/** @internal */
+export interface TaxPaymentRow {
+    payment: TaxPayment;
+    status: TaxPaymentStatus;
+}
+/** @internal */
+export interface TaxPaymentsListPresentationProps {
+    /** CSS class name applied to the root element. */
+    className?: string;
+    /** Rows for the current page, already filtered and searched. */
+    rows: TaxPaymentRow[];
+    /** Number of overdue payments, regardless of the active filters. */
+    overdueCount: number;
+    /** Distinct jurisdictions across all payments, used to build the jurisdiction filter. */
+    jurisdictions: string[];
+    /** Whether the company has any tax payments at all, before filtering. */
+    hasPayments: boolean;
+    /** Whether the fetched list hit the page cap and omits older payments. */
+    isTruncated: boolean;
+    searchValue: string;
+    onSearchChange: (value: string) => void;
+    jurisdictionFilter: string;
+    onJurisdictionFilterChange: (value: string) => void;
+    statusFilter: string;
+    onStatusFilterChange: (value: string) => void;
+    pagination: PaginationControlProps;
+    onViewPayment: (taxPaymentId: string) => void;
+}
+/** @internal */
+export declare function TaxPaymentsListPresentation({ className, rows, overdueCount, jurisdictions, hasPayments, isTruncated, searchValue, onSearchChange, jurisdictionFilter, onJurisdictionFilterChange, statusFilter, onStatusFilterChange, pagination, onViewPayment, }: TaxPaymentsListPresentationProps): import('react').JSX.Element;

package/dist/src/components/Company/TaxPayments/index.d.ts

@@ -0,0 +1,6 @@
+export { TaxPaymentsFlow } from './TaxPaymentsFlow/TaxPaymentsFlow';
+export type { TaxPaymentsFlowProps } from './TaxPaymentsFlow/TaxPaymentsFlowComponents';
+export { TaxPaymentsList } from './TaxPaymentsList/TaxPaymentsList';
+export type { TaxPaymentsListProps } from './TaxPaymentsList/TaxPaymentsList';
+export { TaxPaymentDetail } from './TaxPaymentDetail/TaxPaymentDetail';
+export type { TaxPaymentDetailProps } from './TaxPaymentDetail/TaxPaymentDetail';

package/dist/src/components/Company/TaxPayments/shared/payrollLookupWindow.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A `start_date`/`end_date` pair for the payrolls list endpoint.
+ *
+ * @internal
+ */
+export interface PayrollLookupWindow {
+    /** Inclusive lower bound, as `YYYY-MM-DD`. */
+    startDate: string;
+    /** Inclusive upper bound, as `YYYY-MM-DD`. */
+    endDate: string;
+}
+/**
+ * Builds the payroll-lookup window used to resolve a tax payment's liability pay periods.
+ *
+ * @remarks
+ * Pads the tax period on both ends, then clamps to the payrolls endpoint's two documented limits —
+ * a maximum 367-day span and an `end_date` no more than 93 days ahead of today. Annual tax periods
+ * (FUTA, for example) exceed both once padded, so clamping is what keeps the request valid.
+ *
+ * Clamping can leave liabilities outside the window; the caller resolves those individually, so a
+ * narrowed window costs extra requests rather than correctness.
+ *
+ * @param periodStart - Tax period start as `YYYY-MM-DD`. Falls back to `periodEnd` when absent.
+ * @param periodEnd - Tax period end as `YYYY-MM-DD`.
+ * @param today - Today's date as `YYYY-MM-DD`, used for the future-end-date clamp.
+ * @returns The window, or `undefined` when the dates cannot be parsed.
+ * @internal
+ */
+export declare function buildPayrollLookupWindow(periodStart: string | undefined, periodEnd: string | undefined, today: string): PayrollLookupWindow | undefined;

package/dist/src/components/Company/TaxPayments/shared/payrollLookupWindow.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/components/Company/TaxPayments/shared/taxPaymentStatus.d.ts

@@ -0,0 +1,62 @@
+import { TaxPayment } from '@gusto/embedded-api/models/components/taxpayment';
+/** @internal */
+export type TaxPaymentStatus = 'paid' | 'scheduled' | 'overdue' | 'refund';
+/** @internal */
+export declare const TAX_PAYMENT_STATUSES: readonly TaxPaymentStatus[];
+/**
+ * Value of the "show everything" entry in the jurisdiction and status filters.
+ *
+ * @remarks
+ * A non-empty sentinel rather than `''` so the filter has a real selected key — an empty key reads
+ * as "no selection" to the underlying select, which renders the placeholder instead of the option
+ * and cannot be distinguished from being cleared.
+ *
+ * @internal
+ */
+export declare const ALL_FILTER_VALUE = "all";
+/** @internal */
+export declare const FEDERAL_JURISDICTION = "US";
+/** @internal */
+export declare const TAX_PAYMENT_STATUS_BADGES: Record<TaxPaymentStatus, 'info' | 'success' | 'warning' | 'error'>;
+/** @internal */
+export declare function isFederalTaxPayment(payment: Pick<TaxPayment, 'jurisdiction'>): boolean;
+/**
+ * Resolves the translation key and interpolation values for a tax payment's jurisdiction label.
+ *
+ * @remarks
+ * Returns a key rather than a string because `Company.Management.TaxPaymentsList` and
+ * `Company.Management.TaxPaymentDetail` each own their own i18n namespace and must translate from it. This
+ * keeps the federal/state branching in one place while leaving the lookup to the caller.
+ *
+ * @param payment - The tax payment to label.
+ * @returns The translation key and its interpolation values.
+ * @internal
+ */
+export declare function getJurisdictionLabel(payment: Pick<TaxPayment, 'jurisdiction'>): {
+    key: 'federal' | 'state';
+    values: {
+        jurisdiction: string;
+    };
+};
+/**
+ * Derives a display status for a tax payment.
+ *
+ * @remarks
+ * The API has no status field, so status is derived from the amounts and dates. The API sends
+ * `payment_sent_on: null` for both never-sent and returned/cancelled payments, so a
+ * returned/cancelled state cannot be distinguished here.
+ *
+ * Settlement is checked before the amount's sign, so a refund that has already been sent or
+ * reimbursed reads as `paid` rather than staying `refund` forever.
+ *
+ * A zero-amount payment owes nothing and will never be sent, so it reads as `paid` rather than
+ * sitting in `scheduled` indefinitely. The list endpoint does return zero-amount payments — it
+ * applies `.for_taxes.non_penalty` but not `.with_amounts` — so this is a real case, not a
+ * theoretical one.
+ *
+ * @param payment - The tax payment to classify.
+ * @param today - Today's date as a `YYYY-MM-DD` string in the user's local timezone.
+ * @returns The derived status.
+ * @internal
+ */
+export declare function deriveTaxPaymentStatus(payment: Pick<TaxPayment, 'amount' | 'amountPaid' | 'dueDate' | 'paymentSentOn'>, today: string): TaxPaymentStatus;

package/dist/src/components/Company/TaxPayments/shared/taxPaymentStatus.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/components/Company/TaxPayments/shared/useAllTaxPayments.d.ts

@@ -0,0 +1,30 @@
+import { TaxPayment } from '@gusto/embedded-api/models/components/taxpayment';
+/**
+ * Result of {@link useAllTaxPayments}.
+ *
+ * @internal
+ */
+export interface AllTaxPaymentsResult {
+    /** Every tax payment fetched, newest due date first. */
+    taxPayments: TaxPayment[];
+    /** Whether the server reported more pages than {@link MAX_PAGES} and the list was truncated. */
+    isTruncated: boolean;
+}
+/**
+ * Fetches a company's tax payments so filtering, search, and pagination can be applied client-side.
+ *
+ * @remarks
+ * Suspends until every fetched page resolves. Filtering and search stay client-side deliberately:
+ * the derived `Overdue` and `Scheduled` statuses depend on "not yet sent", which the API exposes no
+ * filter for, the `jurisdiction` filter would silently drop local/city agencies that still report a
+ * state code, and there is no text-search parameter at all.
+ *
+ * Fetching is capped at {@link MAX_PAGES} pages because the endpoint paginates an in-memory array —
+ * each page request reloads the company's full payment history server-side, so an uncapped fan-out
+ * multiplies that cost rather than amortizing it.
+ *
+ * @param companyId - The company whose tax payments are fetched.
+ * @returns The fetched tax payments and whether the list was truncated.
+ * @internal
+ */
+export declare function useAllTaxPayments(companyId: string): AllTaxPaymentsResult;

package/dist/src/components/Company/exports/companyManagement.d.ts

@@ -1,2 +1,4 @@
 export { PaySchedule, type PayScheduleProps, type PayScheduleDictionary, } from '../PaySchedule/management';
 export { PayScheduleAssignment, type PayScheduleAssignmentProps, } from '../PaySchedule/management/PayScheduleAssignment';
+export { TaxPaymentsFlow, TaxPaymentsList, TaxPaymentDetail } from '../TaxPayments';
+export type { TaxPaymentsFlowProps, TaxPaymentsListProps, TaxPaymentDetailProps, } from '../TaxPayments';

package/dist/src/components/Employee/Profile/shared/useEmployeeDetailsForm/employeeDetailsSchema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/components/Payroll/PayrollConfiguration/__fixtures__/payrollConfigurationMocks.d.ts

@@ -261,6 +261,11 @@ interface PayrollHandlersOptions {
     getPayrollData: () => ReturnType<typeof buildPayrollData>;
     /** Employees returned by the paginated list endpoint. Defaults to all 27. */
     employees?: Array<ReturnType<typeof createEmployee>>;
+    /**
+     * Employees per page returned by the list endpoint, overriding the requested `per`.
+     * Lets pagination tests page through a few rows instead of rendering 25 per page.
+     */
+    pageSize?: number;
     /** Pay schedule returned by the pay-schedule endpoint. */
     paySchedule?: typeof mockPaySchedule;
     /** Blockers returned by the blockers endpoint. Defaults to none. */
@@ -272,5 +277,5 @@ interface PayrollHandlersOptions {
  * and pay schedule. Tests spread these into `server.use(...)` and add/override
  * endpoint handlers (e.g. `calculate`) as needed.
  */
-export declare const buildPayrollConfigurationHandlers: ({ getPayrollData, employees, paySchedule, blockers, }: PayrollHandlersOptions) => HttpHandler[];
+export declare const buildPayrollConfigurationHandlers: ({ getPayrollData, employees, paySchedule, blockers, pageSize, }: PayrollHandlersOptions) => HttpHandler[];
 export {};

package/dist/src/components/Payroll/PayrollFlow/PayrollFlow.d.ts

@@ -19,6 +19,7 @@ import { PayrollFlowProps } from './PayrollFlowComponents';
  * | `runPayroll/processed` | Payroll processing completes | — |
  * | `runPayroll/processingFailed` | Payroll processing fails | Error details |
  * | `runPayroll/cancelled` | A submitted payroll is cancelled | `{ payrollId: string, result: object }` |
+ * | `runPayroll/notCalculated/backToList` | User returns to the payroll list from a payroll that is no longer calculated | — |
  * | `runPayroll/summary/viewed` | The summary screen is opened | `{ payrollId: string }` |
  * | `runPayroll/receipt/viewed` | The receipt screen is opened | `{ payrollId: string }` |
  * | `runPayroll/offCycle/start` | The user starts an off-cycle payroll | — |

package/dist/src/components/Payroll/PayrollLanding/PayrollLanding.d.ts

@@ -35,6 +35,7 @@ export interface PayrollLandingProps extends BaseComponentInterface<'Payroll.Pay
  * | `runPayroll/receipt/viewed` | User opened a payroll's receipt view | `{ payrollId: string }` |
  * | `runPayroll/blockers/viewAll` | User opened the full list of payroll blockers | — |
  * | `runPayroll/cancelled` | A payroll was cancelled | `{ payrollId: string, result: object }` |
+ * | `runPayroll/notCalculated/backToList` | User returns to the payroll list from a payroll that is no longer calculated | — |
  * | `runPayroll/cancelled/alertDismissed` | User dismissed the payroll-cancelled success alert | — |
  *
  * When unprocessed transition pay periods exist, the landing surface renders a Transition

package/dist/src/components/Payroll/PayrollOverview/PayrollOverview.d.ts

@@ -9,7 +9,10 @@ import { BaseComponentInterface } from '../../Base';
 export interface PayrollOverviewProps extends BaseComponentInterface<'Payroll.PayrollOverview'> {
     /** Identifier of the company that owns the payroll. */
     companyId: string;
-    /** Identifier of the payroll being reviewed. The payroll must already be calculated. */
+    /**
+     * Identifier of the payroll being reviewed. An unprocessed payroll must already be calculated;
+     * a processed payroll renders as a summary whether or not it has a calculation.
+     */
     payrollId: string;
     /** Alert banners to display above the payroll summary. */
     alerts?: PayrollFlowAlert[];
@@ -30,8 +33,10 @@ export interface PayrollOverviewProps extends BaseComponentInterface<'Payroll.Pa
  * and per-employee paystub downloads once complete.
  *
  * @remarks
- * The payroll referenced by `payrollId` must already be calculated; rendering with an
- * uncalculated payroll throws. Unresolved submission blockers (e.g. fast-ACH threshold,
+ * An unprocessed payroll referenced by `payrollId` must already be calculated; rendering an
+ * unprocessed, uncalculated payroll throws. Processed payrolls render as a summary even without a
+ * calculation (for example tax reconciliation, reversal, wage correction, or external payrolls).
+ * Unresolved submission blockers (e.g. fast-ACH threshold,
  * wire-in funding) are surfaced inline and the submit action stays disabled until each
  * blocker has a selected unblock option. While the payroll is processing, the component
  * polls until success or failure and emits the corresponding event. Pass `readOnly` to hide
@@ -46,6 +51,7 @@ export interface PayrollOverviewProps extends BaseComponentInterface<'Payroll.Pa
  * | `runPayroll/processed` | Payroll finished processing successfully | `{ payPeriod, payrollUuid }` |
  * | `runPayroll/processingFailed` | Payroll processing failed | — |
  * | `runPayroll/cancelled` | Payroll was cancelled | Cancel payroll response |
+ * | `runPayroll/notCalculated/backToList` | User chose to return to the payroll list after the payroll was found to be no longer calculated (e.g. cancelled in another session) | — |
  * | `runPayroll/receipt/get` | User requested the payroll receipt | `{ payrollId }` |
  * | `runPayroll/pdfPaystub/viewed` | User opened an employee's paystub PDF | `{ employeeId }` |
  * | `payroll/wire/form/done` | Wire-in details were confirmed via the embedded wire form | Submit wire-in response |

package/dist/src/components/Payroll/helpers.d.ts

@@ -169,19 +169,6 @@ export declare const getPayrollType: (payroll: {
  * @internal
  */
 export declare const isDismissalPayroll: (offCycleReason?: string | null) => boolean;
-/**
- * Returns whether an off-cycle reason indicates a tax reconciliation payroll.
- *
- * @remarks
- * Tax reconciliation payrolls are created by Gusto rather than run by the partner. They come
- * back processed with no pay period and no `calculatedAt`, so callers use this to grant them a
- * targeted exception from checks that otherwise assume every payroll has both.
- *
- * @param offCycleReason - The payroll's off-cycle reason string.
- * @returns `true` when the reason matches the tax reconciliation reason.
- * @internal
- */
-export declare const isTaxReconciliationPayroll: (offCycleReason?: string | null) => boolean;
 /**
  * Returns a formatted pay-period range, falling back to the formatted check date when the
  * payroll has no pay period.
@@ -243,14 +230,23 @@ export declare const getAdditionalEarningsCompensations: ({ flsaStatus, existing
  */
 export declare const calculateTotalPayroll: (payrollData: Payroll) => number;
 /**
- * Determines whether a payroll can be cancelled based on its status, deadline, and the 4:00 PM PT cutoff.
+ * Returns whether to show the cancel action for a payroll.
  *
  * @remarks
- * Returns `true` only when the payroll has been processed, `payrollStatusMeta.cancellable` is not explicitly `false`,
- * the payroll has a `payrollDeadline`, and the current time is before 4:00 PM Pacific Time on that deadline date.
+ * Shows cancel only when the API will accept it:
+ *
+ * - `payrollStatusMeta.cancellable` is `true`. A missing flag hides cancel, so fetch the payroll
+ *   with `payroll_status_meta`.
+ * - The payroll is processed and not external.
+ * - It is a regular payroll, or an off-cycle payroll with one of the reasons listed above. The
+ *   `cancellable` flag does not check the payroll type yet, so this helper does.
+ * - It is before 4:00 PM PT on the `payrollDeadline` date, so a page left open past the cutoff
+ *   stops offering cancel.
+ *
+ * The API can still refuse if a tax filing was already sent. The payroll data doesn't show that.
  *
- * @param payroll - The payroll to evaluate.
- * @returns `true` if the payroll is still cancellable, `false` otherwise.
+ * @param payroll - The payroll to check, fetched with `payroll_status_meta`.
+ * @returns `true` if cancel should be shown.
  * @internal
  */
 export declare const canCancelPayroll: (payroll: Payroll) => boolean;

package/dist/src/contexts/ApiProvider/createSdkQueryClient.d.ts

@@ -5,6 +5,8 @@ import { QueryClient } from '@tanstack/react-query';
  * @remarks
  * Defaults applied:
  * - `retry: false` on both queries and mutations.
+ * - `networkMode: 'always'` on both queries and mutations, so requests made while the browser reports offline fail with an error instead of
+ *   staying paused (and showing an indefinite loading state) until connectivity returns.
  * - On any successful mutation, every SDK query under the namespace is invalidated so the next read refetches fresh data.
  *
  * {@link ApiProvider} uses this when no `queryClient` prop is supplied, and `GustoTestProvider` uses it so tests faithfully replicate production

package/dist/src/contexts/ApiProvider/createSdkQueryClient.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/contexts/ApiProvider/payrollOffCycleReasonEnumHook.d.ts

@@ -0,0 +1,14 @@
+import { AfterSuccessHook } from '../../types/hooks';
+/**
+ * Temporary workaround for a Gusto-Partner-API spec gap: `off_cycle_reason` on payroll responses
+ * is generated as a closed enum (`z.nativeEnum(OffCycleReasonType)`) in `@gusto/embedded-api`, but
+ * the API also emits reasons the published OAS doesn't list (e.g. `Max out 401k`, `Other`). A
+ * single such payroll makes the whole `GetV1CompaniesCompanyIdPayrolls` response throw an
+ * `SDKValidationError`, taking down Payroll History and every other payroll list for the company.
+ * This afterSuccess hook nulls out any reason outside the closed enum before the SDK's zod parse,
+ * so the response still validates and the payroll renders as a generic off-cycle payroll. Remove
+ * once the client supports lax/open enum parsing for this field.
+ *
+ * @internal
+ */
+export declare const payrollOffCycleReasonEnumHook: AfterSuccessHook;

package/dist/src/contexts/ApiProvider/payrollOffCycleReasonEnumHook.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/contexts/ObservabilityProvider/sanitization.d.ts

@@ -12,7 +12,8 @@ export declare function sanitizeString(value: string): string;
  *
  * @remarks
  * Keys whose names match (case-insensitively contain) any built-in sensitive field name or any
- * entry in `additionalSensitiveFields` have their values replaced with `[REDACTED]`. String
+ * entry in `additionalSensitiveFields` have their values replaced with `[REDACTED]`. Short names
+ * (`ein`, `dob`, `zip`, `city`) match the whole key, case-insensitively. String
  * values are passed through {@link sanitizeString} so PII patterns inside them are also redacted.
  * Numbers, booleans, `null`, and `undefined` pass through unchanged.
  *
@@ -23,32 +24,22 @@ export declare function sanitizeString(value: string): string;
  */
 export declare function sanitizeObject(obj: unknown, additionalSensitiveFields?: string[]): unknown;
 /**
- * Returns a copy of an observability error with PII redacted from messages and field-error metadata.
+ * Redacts error messages and field-error metadata before and after a custom sanitizer runs.
  *
  * @remarks
- * If `config.customErrorSanitizer` is provided, it is invoked and its result returned directly.
- * When sanitization is disabled, the error passes through unchanged except that `raw` is stripped
- * unless `includeRawError` is true. When enabled, `message` and each `fieldErrors[].message` run
- * through {@link sanitizeString}, and each `fieldErrors[].metadata` runs through {@link sanitizeObject}
- * with `additionalSensitiveFields` applied.
+ * `enabled: false` skips redaction. Independently, `raw` is excluded before and after the
+ * custom sanitizer unless `includeRawError: true`. Opted-in `raw` is passed through unchanged.
+ * Other error properties are preserved without redaction.
  *
- * @param error - The error reported by SDK error boundaries or form submissions.
- * @param config - Optional sanitization configuration; defaults to enabled with `raw` stripped.
- * @returns The sanitized error suitable for forwarding to a partner observability hook.
  * @internal
  */
 export declare function sanitizeError(error: ObservabilityError, config?: SanitizationConfig): ObservabilityError;
 /**
- * Returns a copy of an observability metric with sensitive values redacted from its tags.
+ * Redacts metric tags before and after a custom sanitizer runs, unless `enabled: false`.
  *
  * @remarks
- * If `config.customMetricSanitizer` is provided, it is invoked and its result returned directly.
- * When sanitization is disabled, the metric passes through unchanged. Otherwise the `tags` record
- * is run through {@link sanitizeObject} with `additionalSensitiveFields` applied.
+ * Other metric properties are preserved without redaction.
  *
- * @param metric - The metric reported by SDK component instrumentation.
- * @param config - Optional sanitization configuration; defaults to enabled.
- * @returns The sanitized metric suitable for forwarding to a partner observability hook.
  * @internal
  */
 export declare function sanitizeMetric(metric: ObservabilityMetric, config?: SanitizationConfig): ObservabilityMetric;

package/dist/src/contexts/ObservabilityProvider/useSanitizedObservability.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/contexts/UnstableFeaturesProvider/useUnstableFeature.d.ts

@@ -21,6 +21,8 @@ export interface UnstableFeatures {
     payrollRegularRateOfPay?: boolean;
     /** Enables the in-development `CompanyManagement.PaySchedule` flow for managing pay schedules and their assignments after onboarding. */
     managePaySchedules?: boolean;
+    /** Enables the in-development `CompanyManagement.TaxPaymentsFlow` for reviewing a company's tax payments and their liabilities. */
+    taxPayments?: boolean;
 }
 /**
  * React context backing {@link useUnstableFeature}.

package/dist/src/helpers/validations.test.d.ts

@@ -0,0 +1 @@
+export {};