Skip to content

feat(Contractor.Documents): document list, W-9 signing, and signer flow #2292

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
serikjensen wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

feat(Contractor.Documents): document list, W-9 signing, and signer flow #2292

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ab53d16
feat(Contractor.Documents): add document list, W-9 signing, and signe…
serikjensen Jun 26, 2026
47a44ad
chore: update derived files
github-actions[bot] Jun 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 190 additions & 2 deletions .reports/embedded-react-sdk.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ import { ContractorType as ContractorType_2 } from '@gusto/embedded-api-v-2025-1
import { Control } from 'react-hook-form';
import { CustomTypeOptions } from 'i18next';
import { default as default_2 } from 'react';
import { Document as Document_2 } from '@gusto/embedded-api-v-2025-11-15/models/components/document';
import { DocumentSigned } from '@gusto/embedded-api-v-2025-11-15/models/components/documentsigned';
import { Employee } from '@gusto/embedded-api-v-2025-11-15/models/components/employee';
import { EmployeeAddress } from '@gusto/embedded-api-v-2025-11-15/models/components/employeeaddress';
import { EmployeeBankAccount } from '@gusto/embedded-api-v-2025-11-15/models/components/employeebankaccount';
Expand Down Expand Up @@ -147,6 +149,9 @@ export { AfterSuccessContext }

export { AfterSuccessHook }

// @public
export const AGREE_FIELD = "agree";

// @public
export interface AlertProps {
action?: ReactNode;
Expand Down Expand Up @@ -376,6 +381,15 @@ export interface BreadcrumbsProps {
onClick?: (id: string) => void;
}

// @public
export function buildContractorSignatureFields(descriptors: W9FieldDescriptor[]): ContractorSignatureFields;

// @public
export function buildW9Defaults(document: Document_2, descriptors: W9FieldDescriptor[]): ContractorSignatureFormData;

// @public
export function buildW9FieldDescriptors(document: Document_2): W9FieldDescriptor[];

// @public
export interface ButtonIconProps extends ButtonProps {
'aria-label': string;
Expand Down Expand Up @@ -895,6 +909,9 @@ export const componentEvents: {
readonly CONTRACTOR_ONBOARDING_STATUS_UPDATED: "contractor/onboardingStatus/updated";
readonly CONTRACTOR_INVITE_CONTRACTOR: "contractor/invite/selfOnboarding";
readonly CONTRACTOR_ONBOARDING_CONTINUE: "contractor/onboarding/continue";
readonly CONTRACTOR_VIEW_DOCUMENT_TO_SIGN: "contractor/documents/view";
readonly CONTRACTOR_SIGN_DOCUMENT: "contractor/documents/sign";
readonly CONTRACTOR_DOCUMENTS_DONE: "contractor/documents/done";
readonly PAY_SCHEDULE_CREATE: "paySchedule/create";
readonly PAY_SCHEDULE_CREATED: "paySchedule/created";
readonly PAY_SCHEDULE_UPDATE: "paySchedule/update";
Expand Down Expand Up @@ -1283,6 +1300,14 @@ export interface ContractorDetailsSubmitOptions {
companyId?: string;
}

// @public
function ContractorDocumentSigner(props: ContractorDocumentSignerProps): JSX;

// @public
interface ContractorDocumentSignerProps extends BaseComponentInterface {
contractorId: string;
}

// @public
export function ContractorEinField(props: ContractorEinFieldProps): JSX;

Expand Down Expand Up @@ -1371,7 +1396,13 @@ declare namespace ContractorOnboarding {
NewHireReport,
NewHireReportProps,
ContractorSubmit,
ContractorSubmitProps
ContractorSubmitProps,
ContractorDocumentSigner,
ContractorDocumentSignerProps,
DocumentsList,
DocumentsListProps,
SignatureForm_3 as SignatureForm,
SignatureFormProps_3 as SignatureFormProps
}
}

Expand Down Expand Up @@ -1405,6 +1436,41 @@ export type ContractorSelfOnboardingFieldProps = HookFieldProps<SwitchHookFieldP
// @public
export const ContractorSelfOnboardingStatuses: Set<ContractorOnboardingStatus1>;

// @public
export type ContractorSignatureBoundField = ComponentType<ContractorSignatureFieldProps>;

// @public
export interface ContractorSignatureFieldProps {
description?: ReactNode;
getOptionLabel?: (value: string) => string;
label: string;
placeholder?: string;
validationMessages?: ValidationMessages<ContractorSignatureFormErrorCode>;
}

// @public
export type ContractorSignatureFields = Record<string, ContractorSignatureBoundField>;

// @public
export type ContractorSignatureFormData = Record<string, string | boolean> & {
agree: boolean;
};

// @public
export type ContractorSignatureFormErrorCode = (typeof ContractorSignatureFormErrorCodes)[keyof typeof ContractorSignatureFormErrorCodes];

// @public
export const ContractorSignatureFormErrorCodes: {
readonly REQUIRED: "REQUIRED";
readonly AGREE_REQUIRED: "AGREE_REQUIRED";
};

// @public
export interface ContractorSignatureSection {
fieldNames: string[];
section: W9Section;
}

// @public
export function ContractorSsnField(props: ContractorSsnFieldProps): JSX;

Expand Down Expand Up @@ -1538,6 +1604,9 @@ state: z.ZodString;
zip: z.ZodString;
}>;

// @public
export function createContractorSignatureFormSchema(descriptors: W9FieldDescriptor[]): z.ZodType<ContractorSignatureFormData, ContractorSignatureFormData>;

// Warning: (ae-forgotten-export) The symbol "DeductionFormSchemaOptions" needs to be exported by the entry point index.d.ts
// Warning: (ae-internal-missing-underscore) The name "createDeductionFormSchema" should be prefixed with an underscore because the declaration is marked as @internal
//
Expand Down Expand Up @@ -2099,6 +2168,14 @@ interface DocumentSignerProps_2 extends BaseComponentInterface<'Company.Document
signatoryId?: string;
}

// @public
function DocumentsList(props: DocumentsListProps): JSX;

// @public
interface DocumentsListProps extends BaseComponentInterface<'Contractor.DocumentsList'> {
contractorId: string;
}

// @public
interface DocumentsProps extends BaseComponentInterface<'Employee.Management.Documents'> {
employeeId: string;
Expand Down Expand Up @@ -2555,6 +2632,7 @@ export interface FieldMetadata {
maxDate?: string | null;
minDate?: string | null;
name: string;
placeholder?: string;
}

// @public
Expand Down Expand Up @@ -3020,6 +3098,9 @@ interface InviteSignatoryProps extends BaseComponentInterface<'Company.AssignSig
defaultValues?: InviteSignatoryDefaultValues;
}

// @public
export function isW9Document(document: Document_2): boolean;

// @public
export type JobErrorCode = (typeof JobErrorCodes)[keyof typeof JobErrorCodes];

Expand Down Expand Up @@ -3155,6 +3236,15 @@ export interface LinkProps extends Pick<AnchorHTMLAttributes<HTMLAnchorElement>,
children?: ReactNode;
}

// @public
export const LLC_CLASSIFICATION_CODES: readonly ["c", "s", "p"];

// @public
export const LLC_CLASSIFICATION_FIELD = "llcClassificationCode";

// @public
export const LLC_CLASSIFICATION_OPTION: TaxClassificationOptionKey;

// @public
export interface LoadingSpinnerProps extends Pick<HTMLAttributes<HTMLDivElement>, 'className' | 'id' | 'aria-label'> {
size?: 'lg' | 'sm';
Expand Down Expand Up @@ -3557,6 +3647,12 @@ export function OrderNumberField(props: OrderNumberFieldProps): JSX;
// @public
export type OrderNumberFieldProps = HookFieldProps<TextInputHookFieldProps<ChildSupportGarnishmentRequiredValidation>>;

// @public
export const OTHER_CLASSIFICATION_OPTION: TaxClassificationOptionKey;

// @public
export const OTHER_TEXT_FIELD = "other_text";

// @public
export function OtherIncomeField(props: OtherIncomeFieldProps): JSX;

Expand Down Expand Up @@ -4451,6 +4547,11 @@ interface SelfOnboardingFlowProps extends BaseComponentInterface<never> {
withEmployeeI9?: boolean;
}

// Warning: (ae-forgotten-export) The symbol "SignFieldValue" needs to be exported by the entry point index.d.ts
//
// @public
export function serializeW9Fields(document: Document_2, descriptors: W9FieldDescriptor[], values: ContractorSignatureFormData): SignFieldValue[];

// @public
export interface SharedFieldLayoutProps extends DataAttributes {
description?: ReactNode;
Expand All @@ -4475,6 +4576,9 @@ function SignatureForm(props: SignatureFormProps): JSX;
// @public
function SignatureForm_2(props: SignatureFormProps_2): JSX;

// @public
function SignatureForm_3(props: SignatureFormProps_3): JSX;

// @public
interface SignatureFormProps extends BaseComponentInterface<'Employee.DocumentSigner'> {
employeeId: string;
Expand All @@ -4489,6 +4593,12 @@ interface SignatureFormProps_2 extends BaseComponentInterface<'Company.Signature
formId: string;
}

// @public
interface SignatureFormProps_3 extends BaseComponentInterface<'Contractor.SignatureForm'> {
contractorId: string;
documentUuid: string;
}

// @public
export type SignCompanyFormData = { signature: string; confirmSignature: boolean; };

Expand Down Expand Up @@ -4860,6 +4970,15 @@ export interface TabsProps {
tabs: TabProps[];
}

// @public
export const TAX_CLASSIFICATION_FIELD = "taxClassification";

// @public
export const TAX_CLASSIFICATION_OPTION_KEYS: readonly ["individual_proprietor", "c_corporation", "s_corporation", "partnership", "trust_estate", "limited_liability_company", "other"];

// @public
export type TaxClassificationOptionKey = (typeof TAX_CLASSIFICATION_OPTION_KEYS)[number];

// @public
function TerminateEmployee(props: TerminateEmployeeProps): JSX;

Expand Down Expand Up @@ -5291,6 +5410,54 @@ export type UseContractorDetailsFormSharedProps = {
shouldFocusError?: boolean;
};

// @public
export function useContractorDocumentsList(input: UseContractorDocumentsListParams): UseContractorDocumentsListResult;

// @public
export interface UseContractorDocumentsListParams {
contractorId: string;
}

// @public
export type UseContractorDocumentsListReady = BaseHookReady<{
documents: Document_2[];
}, {
isFetching: boolean;
}>;

// @public
export type UseContractorDocumentsListResult = HookLoadingResult | UseContractorDocumentsListReady;

// @public
export function useContractorSignatureForm(input: UseContractorSignatureFormProps): UseContractorSignatureFormResult;

// @public
export interface UseContractorSignatureFormProps {
documentUuid: string;
shouldFocusError?: boolean;
validationMode?: UseFormProps['mode'];
}

// @public
export interface UseContractorSignatureFormReady extends BaseFormHookReady<FieldsMetadata, ContractorSignatureFormData, ContractorSignatureFields> {
actions: {
onSubmit: () => Promise<HookSubmitResult<DocumentSigned> | undefined>;
};
data: {
document: Document_2;
pdfUrl: string | null;
sections: ContractorSignatureSection[];
hasFields: boolean;
};
status: {
isPending: boolean;
mode: 'create';
};
}

// @public
export type UseContractorSignatureFormResult = HookLoadingResult | UseContractorSignatureFormReady;

// @public
export function useCurrentHomeAddressForm(props: UseCurrentHomeAddressFormProps): UseHomeAddressFormResult;

Expand Down Expand Up @@ -5778,6 +5945,27 @@ interface ViewHolidayScheduleProps extends BaseComponentInterface<'Company.TimeO
companyId: string;
}

// @public
export const W9_DOCUMENT_NAME = "taxpayer_identification_form_w_9";

// @public
export interface W9FieldDescriptor {
apiKey?: string;
hasRedactedValue?: boolean;
isRequired: boolean;
name: string;
placeholder?: string;
section: W9Section;
variant: W9FieldVariant;
visibleWhenClassification?: TaxClassificationOptionKey;
}

// @public
export type W9FieldVariant = 'text' | 'checkbox' | 'radio' | 'select';

// @public
export type W9Section = 'classification' | 'exemptions' | 'address' | 'tin' | 'certification';

// @public
export const WageType: {
readonly Fixed: "Fixed";
Expand Down Expand Up @@ -5893,7 +6081,7 @@ export type ZipValidation = (typeof HomeAddressErrorCodes)['REQUIRED' | 'INVALID

// Warnings were encountered during analysis:
//
// dist/partner-hook-utils/types.d.ts:270:13 - (ae-forgotten-export) The symbol "FieldElementRegistry" needs to be exported by the entry point index.d.ts
// dist/partner-hook-utils/types.d.ts:272:13 - (ae-forgotten-export) The symbol "FieldElementRegistry" needs to be exported by the entry point index.d.ts

// (No @packageDocumentation comment for this package)

Expand Down
54 changes: 54 additions & 0 deletions docs/appendix/endpoint-inventory.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1791,6 +1791,60 @@
"contractorUuid"
]
},
"ContractorOnboarding.ContractorDocumentSigner": {
"endpoints": [
{
"method": "GET",
"path": "/v1/contractors/:contractorUuid/documents"
},
{
"method": "GET",
"path": "/v1/documents/:documentUuid"
},
{
"method": "GET",
"path": "/v1/documents/:documentUuid/pdf"
},
{
"method": "PUT",
"path": "/v1/documents/:documentUuid/sign"
}
],
"variables": [
"contractorUuid",
"documentUuid"
]
},
"ContractorOnboarding.DocumentsList": {
"endpoints": [
{
"method": "GET",
"path": "/v1/contractors/:contractorUuid/documents"
}
],
"variables": [
"contractorUuid"
]
},
"ContractorOnboarding.SignatureForm": {
"endpoints": [
{
"method": "GET",
"path": "/v1/documents/:documentUuid"
},
{
"method": "GET",
"path": "/v1/documents/:documentUuid/pdf"
},
{
"method": "PUT",
"path": "/v1/documents/:documentUuid/sign"
}
],
"variables": [
"documentUuid"
]
},
"ContractorManagement.PaymentsList": {
"endpoints": [
{
Expand Down
Loading
Loading