@gusto/embedded-react-sdk 0.50.0 → 0.51.0

package/dist/components/Contractor/Documents/SignatureForm/useContractorSignatureForm/fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.js","sources":["../../../../../../src/components/Contractor/Documents/SignatureForm/useContractorSignatureForm/fields.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport type { ContractorSignatureFormErrorCodes } from './contractorSignatureFormSchema'\nimport { normalizeEinOrNotApplicable, normalizeSsnOrNotApplicable } from './w9Fields'\nimport type { TextInputHookFieldProps } from '@/partner-hook-utils/form/fields/TextInputHookField'\nimport type { CheckboxHookFieldProps } from '@/partner-hook-utils/form/fields/CheckboxHookField'\nimport type { RadioGroupHookFieldProps } from '@/partner-hook-utils/form/fields/RadioGroupHookField'\nimport type { SelectHookFieldProps } from '@/partner-hook-utils/form/fields/SelectHookField'\nimport {\n  TextInputHookField,\n  CheckboxHookField,\n  RadioGroupHookField,\n  SelectHookField,\n} from '@/partner-hook-utils/form/fields'\nimport type { HookFieldProps } from '@/partner-hook-utils/types'\n\n/**\n * The form-field name of the electronic-signature consent checkbox.\n *\n * @internal\n */\nexport const AGREE_FIELD = 'agree'\n\n// ── Shared prop types ─────────────────────────────────────────────────\n\n/**\n * The required-field error code emitted by most {@link useContractorSignatureForm} fields.\n *\n * @remarks\n * Use as a key in `validationMessages` for text inputs, selects, and radio groups\n * that only emit the `REQUIRED` error. See {@link ContractorSignatureFormErrorCodes}.\n *\n * @public\n */\nexport type RequiredValidation = typeof ContractorSignatureFormErrorCodes.REQUIRED\n\n/**\n * Validation error code emitted by the `Agree` consent checkbox.\n *\n * @remarks\n * Use as a key in `validationMessages` on `Fields.Agree`. See\n * {@link ContractorSignatureFormErrorCodes}.\n *\n * @public\n */\nexport type AgreeValidation = typeof ContractorSignatureFormErrorCodes.AGREE_REQUIRED\n\n/**\n * The format-validation error code emitted by the `ssn` field of {@link useContractorSignatureForm}.\n *\n * @remarks\n * Use as a key in `validationMessages` on `Fields.Ssn`. See\n * {@link ContractorSignatureFormErrorCodes}.\n *\n * @public\n */\nexport type SsnValidation = typeof ContractorSignatureFormErrorCodes.INVALID_SSN\n\n/**\n * The format-validation error code emitted by the `ein` field of {@link useContractorSignatureForm}.\n *\n * @remarks\n * Use as a key in `validationMessages` on `Fields.Ein`. See\n * {@link ContractorSignatureFormErrorCodes}.\n *\n * @public\n */\nexport type EinValidation = typeof ContractorSignatureFormErrorCodes.INVALID_EIN\n\n// ── Field prop types ──────────────────────────────────────────────────\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.Name` component.\n *\n * @public\n */\nexport type NameFieldProps = HookFieldProps<TextInputHookFieldProps<RequiredValidation>>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.TaxClassification` component.\n *\n * @public\n */\nexport type TaxClassificationFieldProps = HookFieldProps<\n  RadioGroupHookFieldProps<RequiredValidation, string>\n>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.HomeAddressStreet1` component.\n *\n * @public\n */\nexport type HomeAddressStreet1FieldProps = HookFieldProps<\n  TextInputHookFieldProps<RequiredValidation>\n>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.HomeAddressCity` component.\n *\n * @public\n */\nexport type HomeAddressCityFieldProps = HookFieldProps<TextInputHookFieldProps<RequiredValidation>>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.HomeAddressState` component.\n *\n * @public\n */\nexport type HomeAddressStateFieldProps = HookFieldProps<TextInputHookFieldProps<RequiredValidation>>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.HomeAddressZip` component.\n *\n * @public\n */\nexport type HomeAddressZipFieldProps = HookFieldProps<TextInputHookFieldProps<RequiredValidation>>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.Ssn` component.\n *\n * @public\n */\nexport type SsnFieldProps = HookFieldProps<\n  TextInputHookFieldProps<SsnValidation, RequiredValidation>\n>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.Ein` component.\n *\n * @public\n */\nexport type EinFieldProps = HookFieldProps<\n  TextInputHookFieldProps<EinValidation, RequiredValidation>\n>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.SignatureText` component.\n *\n * @public\n */\nexport type SignatureTextFieldProps = HookFieldProps<TextInputHookFieldProps<RequiredValidation>>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.Agree` component.\n *\n * @public\n */\nexport type AgreeFieldProps = HookFieldProps<CheckboxHookFieldProps<AgreeValidation>>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.BusinessName` component.\n *\n * @public\n */\nexport type BusinessNameFieldProps = HookFieldProps<TextInputHookFieldProps<RequiredValidation>>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.LlcClassificationCode` component.\n *\n * @public\n */\nexport type LlcClassificationCodeFieldProps = HookFieldProps<\n  SelectHookFieldProps<RequiredValidation, string>\n>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.OtherText` component.\n *\n * @public\n */\nexport type OtherTextFieldProps = HookFieldProps<TextInputHookFieldProps<RequiredValidation>>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.ForeignPartners` component.\n *\n * @public\n */\nexport type ForeignPartnersFieldProps = HookFieldProps<CheckboxHookFieldProps>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.ExemptPayeeCode` component.\n *\n * @public\n */\nexport type ExemptPayeeCodeFieldProps = HookFieldProps<TextInputHookFieldProps<RequiredValidation>>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.ExemptionFromFatca` component.\n *\n * @public\n */\nexport type ExemptionFromFatcaFieldProps = HookFieldProps<\n  TextInputHookFieldProps<RequiredValidation>\n>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.HomeAddressStreet2` component.\n *\n * @public\n */\nexport type HomeAddressStreet2FieldProps = HookFieldProps<\n  TextInputHookFieldProps<RequiredValidation>\n>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.AccountNumber` component.\n *\n * @public\n */\nexport type AccountNumberFieldProps = HookFieldProps<TextInputHookFieldProps<RequiredValidation>>\n\n/**\n * Props accepted by {@link useContractorSignatureForm}'s `Fields.CompanyName` component.\n *\n * @public\n */\nexport type CompanyNameFieldProps = HookFieldProps<TextInputHookFieldProps<RequiredValidation>>\n\n// ── Core fields (always present) ──────────────────────────────────────\n\n/** @internal */\nexport function NameField(props: NameFieldProps) {\n  return <TextInputHookField {...props} name=\"name\" />\n}\n\n/** @internal */\nexport function TaxClassificationField(props: TaxClassificationFieldProps) {\n  return <RadioGroupHookField {...props} name=\"taxClassification\" />\n}\n\n/** @internal */\nexport function HomeAddressStreet1Field(props: HomeAddressStreet1FieldProps) {\n  return <TextInputHookField {...props} name=\"homeAddressStreet1\" />\n}\n\n/** @internal */\nexport function HomeAddressCityField(props: HomeAddressCityFieldProps) {\n  return <TextInputHookField {...props} name=\"homeAddressCity\" />\n}\n\n/** @internal */\nexport function HomeAddressStateField(props: HomeAddressStateFieldProps) {\n  return <TextInputHookField {...props} name=\"homeAddressState\" />\n}\n\n/** @internal */\nexport function HomeAddressZipField(props: HomeAddressZipFieldProps) {\n  return <TextInputHookField {...props} name=\"homeAddressZip\" />\n}\n\n/** @internal */\nexport function SsnField(props: SsnFieldProps) {\n  return <TextInputHookField {...props} name=\"ssn\" transform={normalizeSsnOrNotApplicable} />\n}\n\n/** @internal */\nexport function EinField(props: EinFieldProps) {\n  return <TextInputHookField {...props} name=\"ein\" transform={normalizeEinOrNotApplicable} />\n}\n\n/** @internal */\nexport function SignatureTextField(props: SignatureTextFieldProps) {\n  return <TextInputHookField {...props} name=\"signatureText\" />\n}\n\n/** @internal */\nexport function AgreeField(props: AgreeFieldProps) {\n  return <CheckboxHookField {...props} name=\"agree\" />\n}\n\n// ── Variable fields (rendered only when the API returns them) ─────────\n\n/** @internal */\nexport function BusinessNameField(props: BusinessNameFieldProps) {\n  return <TextInputHookField {...props} name=\"businessName\" />\n}\n\n/** @internal */\nexport function LlcClassificationCodeField(props: LlcClassificationCodeFieldProps) {\n  return <SelectHookField {...props} name=\"llcClassificationCode\" />\n}\n\n/** @internal */\nexport function OtherTextField(props: OtherTextFieldProps) {\n  return <TextInputHookField {...props} name=\"otherText\" />\n}\n\n/** @internal */\nexport function ForeignPartnersField(props: ForeignPartnersFieldProps) {\n  return <CheckboxHookField {...props} name=\"foreignPartners\" />\n}\n\n/** @internal */\nexport function ExemptPayeeCodeField(props: ExemptPayeeCodeFieldProps) {\n  return <TextInputHookField {...props} name=\"exemptPayeeCode\" />\n}\n\n/** @internal */\nexport function ExemptionFromFatcaField(props: ExemptionFromFatcaFieldProps) {\n  return <TextInputHookField {...props} name=\"exemptionFromFatca\" />\n}\n\n/** @internal */\nexport function HomeAddressStreet2Field(props: HomeAddressStreet2FieldProps) {\n  return <TextInputHookField {...props} name=\"homeAddressStreet2\" />\n}\n\n/** @internal */\nexport function AccountNumberField(props: AccountNumberFieldProps) {\n  return <TextInputHookField {...props} name=\"accountNumber\" />\n}\n\n/** @internal */\nexport function CompanyNameField(props: CompanyNameFieldProps) {\n  return <TextInputHookField {...props} name=\"companyName\" />\n}\n\n/**\n * Field components exposed by {@link useContractorSignatureForm} on `form.Fields`.\n *\n * @remarks\n * Every field is presence-gated against the API response and is `undefined`\n * when the document didn't return its backing field — always null-check before\n * rendering. This guards against the document API diverging (dropping or\n * renaming a field) by skipping fields it no longer returns, mirroring the\n * stable signing flow. `Agree` is the sole exception: it's a synthesized\n * electronic-signature consent checkbox with no API field, so it's always\n * present.\n *\n * @public\n */\nexport interface ContractorSignatureFormFieldComponents {\n  /** Entity or individual name; defined only when the API returns `name`. */\n  Name: ComponentType<NameFieldProps> | undefined\n  /** Federal tax classification radio group; defined only when the document carries classification checkboxes. */\n  TaxClassification: ComponentType<TaxClassificationFieldProps> | undefined\n  /** Street address line 1; defined only when the API returns `home_address_street_1`. */\n  HomeAddressStreet1: ComponentType<HomeAddressStreet1FieldProps> | undefined\n  /** City; defined only when the API returns `home_address_city`. */\n  HomeAddressCity: ComponentType<HomeAddressCityFieldProps> | undefined\n  /** State; defined only when the API returns `home_address_state`. */\n  HomeAddressState: ComponentType<HomeAddressStateFieldProps> | undefined\n  /** ZIP code; defined only when the API returns `home_address_zip`. */\n  HomeAddressZip: ComponentType<HomeAddressZipFieldProps> | undefined\n  /** Social Security Number; defined only when the API returns `ssn`. */\n  Ssn: ComponentType<SsnFieldProps> | undefined\n  /** Employer Identification Number; defined only when the API returns `ein`. */\n  Ein: ComponentType<EinFieldProps> | undefined\n  /** Typed signature; defined only when the API returns `signature_text`. */\n  SignatureText: ComponentType<SignatureTextFieldProps> | undefined\n  /** Electronic-signature consent checkbox; always present (synthesized, not an API field). */\n  Agree: ComponentType<AgreeFieldProps>\n  /** Business name; defined only when the API returns `business_name`. */\n  BusinessName: ComponentType<BusinessNameFieldProps> | undefined\n  /** LLC tax classification code select; defined only when classification checkboxes are present. */\n  LlcClassificationCode: ComponentType<LlcClassificationCodeFieldProps> | undefined\n  /** \"Other\" free-text classification; defined only when the API returns `other_text`. */\n  OtherText: ComponentType<OtherTextFieldProps> | undefined\n  /** Foreign partners checkbox; defined only when the API returns `foreign_partners`. */\n  ForeignPartners: ComponentType<ForeignPartnersFieldProps> | undefined\n  /** Exempt payee code; defined only when the API returns `exempt_payee_code`. */\n  ExemptPayeeCode: ComponentType<ExemptPayeeCodeFieldProps> | undefined\n  /** FATCA exemption code; defined only when the API returns `exemption_from_FATCA`. */\n  ExemptionFromFatca: ComponentType<ExemptionFromFatcaFieldProps> | undefined\n  /** Street address line 2; defined only when the API returns `home_address_street_2`. */\n  HomeAddressStreet2: ComponentType<HomeAddressStreet2FieldProps> | undefined\n  /** Account number(s); defined only when the API returns `account_number`. */\n  AccountNumber: ComponentType<AccountNumberFieldProps> | undefined\n  /** Requester's name and address; defined only when the API returns `company_name`. */\n  CompanyName: ComponentType<CompanyNameFieldProps> | undefined\n}\n"],"names":["NameField","props","jsx","TextInputHookField","TaxClassificationField","RadioGroupHookField","HomeAddressStreet1Field","HomeAddressCityField","HomeAddressStateField","HomeAddressZipField","SsnField","normalizeSsnOrNotApplicable","EinField","normalizeEinOrNotApplicable","SignatureTextField","AgreeField","CheckboxHookField","BusinessNameField","LlcClassificationCodeField","SelectHookField","OtherTextField","ForeignPartnersField","ExemptPayeeCodeField","ExemptionFromFatcaField","HomeAddressStreet2Field","AccountNumberField","CompanyNameField"],"mappings":";;;;;;AA4NO,SAASA,EAAUC,GAAuB;AAC/C,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,QAAO;AACpD;AAGO,SAASG,EAAuBH,GAAoC;AACzE,SAAO,gBAAAC,EAACG,GAAA,EAAqB,GAAGJ,GAAO,MAAK,qBAAoB;AAClE;AAGO,SAASK,EAAwBL,GAAqC;AAC3E,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,sBAAqB;AAClE;AAGO,SAASM,EAAqBN,GAAkC;AACrE,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,mBAAkB;AAC/D;AAGO,SAASO,EAAsBP,GAAmC;AACvE,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,oBAAmB;AAChE;AAGO,SAASQ,EAAoBR,GAAiC;AACnE,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,kBAAiB;AAC9D;AAGO,SAASS,EAAST,GAAsB;AAC7C,2BAAQE,GAAA,EAAoB,GAAGF,GAAO,MAAK,OAAM,WAAWU,GAA6B;AAC3F;AAGO,SAASC,EAASX,GAAsB;AAC7C,2BAAQE,GAAA,EAAoB,GAAGF,GAAO,MAAK,OAAM,WAAWY,GAA6B;AAC3F;AAGO,SAASC,EAAmBb,GAAgC;AACjE,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,iBAAgB;AAC7D;AAGO,SAASc,EAAWd,GAAwB;AACjD,SAAO,gBAAAC,EAACc,GAAA,EAAmB,GAAGf,GAAO,MAAK,SAAQ;AACpD;AAKO,SAASgB,EAAkBhB,GAA+B;AAC/D,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,gBAAe;AAC5D;AAGO,SAASiB,EAA2BjB,GAAwC;AACjF,SAAO,gBAAAC,EAACiB,GAAA,EAAiB,GAAGlB,GAAO,MAAK,yBAAwB;AAClE;AAGO,SAASmB,EAAenB,GAA4B;AACzD,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,aAAY;AACzD;AAGO,SAASoB,EAAqBpB,GAAkC;AACrE,SAAO,gBAAAC,EAACc,GAAA,EAAmB,GAAGf,GAAO,MAAK,mBAAkB;AAC9D;AAGO,SAASqB,EAAqBrB,GAAkC;AACrE,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,mBAAkB;AAC/D;AAGO,SAASsB,EAAwBtB,GAAqC;AAC3E,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,sBAAqB;AAClE;AAGO,SAASuB,EAAwBvB,GAAqC;AAC3E,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,sBAAqB;AAClE;AAGO,SAASwB,EAAmBxB,GAAgC;AACjE,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,iBAAgB;AAC7D;AAGO,SAASyB,EAAiBzB,GAA8B;AAC7D,SAAO,gBAAAC,EAACC,GAAA,EAAoB,GAAGF,GAAO,MAAK,eAAc;AAC3D;"}

package/dist/components/Contractor/Documents/SignatureForm/useContractorSignatureForm/index.d.ts

@@ -0,0 +1,5 @@
+export { useContractorSignatureForm, type UseContractorSignatureFormProps, type UseContractorSignatureFormReady, type UseContractorSignatureFormResult, type ContractorSignatureFieldsMetadata, } from './useContractorSignatureForm';
+export { ContractorSignatureFormErrorCodes, createContractorSignatureFormSchema, type ContractorSignatureFormErrorCode, type ContractorSignatureFormData, type ContractorSignatureFormOutputs, type ContractorSignatureOptionalFieldsToRequire, type ContractorSignatureSchemaOptions, } from './contractorSignatureFormSchema';
+export { AGREE_FIELD, type ContractorSignatureFormFieldComponents } from './fields';
+export type { RequiredValidation as ContractorSignatureRequiredValidation, AgreeValidation as ContractorSignatureAgreeValidation, SsnValidation as ContractorSignatureSsnValidation, EinValidation as ContractorSignatureEinValidation, NameFieldProps, TaxClassificationFieldProps, HomeAddressStreet1FieldProps, HomeAddressCityFieldProps, HomeAddressStateFieldProps, HomeAddressZipFieldProps, SsnFieldProps as ContractorSignatureSsnFieldProps, EinFieldProps as ContractorSignatureEinFieldProps, SignatureTextFieldProps, AgreeFieldProps as ContractorSignatureAgreeFieldProps, BusinessNameFieldProps, LlcClassificationCodeFieldProps, OtherTextFieldProps, ForeignPartnersFieldProps, ExemptPayeeCodeFieldProps, ExemptionFromFatcaFieldProps, HomeAddressStreet2FieldProps, AccountNumberFieldProps, CompanyNameFieldProps, } from './fields';
+export { W9_DOCUMENT_NAME, TAX_CLASSIFICATION_FIELD, LLC_CLASSIFICATION_FIELD, OTHER_TEXT_FIELD, TAX_CLASSIFICATION_OPTION_KEYS, LLC_CLASSIFICATION_CODES, LLC_CLASSIFICATION_OPTION, OTHER_CLASSIFICATION_OPTION, isW9Document, buildW9Defaults, serializeW9Fields, getPresentFieldNames, getRedactionState, type TaxClassificationOptionKey, type W9RedactionState, type SignFieldValue, } from './w9Fields';

package/dist/components/Contractor/Documents/SignatureForm/useContractorSignatureForm/useContractorSignatureForm.d.ts

@@ -0,0 +1,129 @@
+import { UseFormProps } from 'react-hook-form';
+import { Document } from '@gusto/embedded-api-v-2026-02-01/models/components/document';
+import { DocumentSigned } from '@gusto/embedded-api-v-2026-02-01/models/components/documentsigned';
+import { ContractorSignatureFormData, ContractorSignatureOptionalFieldsToRequire } from './contractorSignatureFormSchema';
+import { ContractorSignatureFormFieldComponents } from './fields';
+import { BaseFormHookReady, FieldMetadata, HookLoadingResult, HookSubmitResult } from '../../../../../partner-hook-utils/types';
+/**
+ * Props for {@link useContractorSignatureForm}.
+ *
+ * @public
+ */
+export interface UseContractorSignatureFormProps {
+    /** UUID of the contractor document to sign. */
+    documentUuid: string;
+    /** When validation runs. Passed through to react-hook-form; defaults to `'onSubmit'`. */
+    validationMode?: UseFormProps['mode'];
+    /** Auto-focus the first invalid field on submit. Defaults to `true`; set to `false` when using `composeSubmitHandler`. */
+    shouldFocusError?: boolean;
+    /** Promote optional W-9 fields to required (e.g. `{ create: ['businessName'] }`). */
+    optionalFieldsToRequire?: ContractorSignatureOptionalFieldsToRequire;
+}
+/**
+ * Ready-state shape returned by {@link useContractorSignatureForm} once the
+ * document metadata has loaded.
+ *
+ * @public
+ */
+export interface UseContractorSignatureFormReady extends BaseFormHookReady<ContractorSignatureFieldsMetadata, ContractorSignatureFormData, ContractorSignatureFormFieldComponents> {
+    /** Loaded data — the document being signed and a downloadable PDF URL. */
+    data: {
+        /** The document entity fetched from the API. */
+        document: Document;
+        /** URL to the document's PDF, or `null` when unavailable. */
+        pdfUrl: string | null;
+        /** Whether the document carries signable fields (vs. acknowledge-only). */
+        hasFields: boolean;
+    };
+    /** Submit-state flags. */
+    status: {
+        /** `true` while the sign mutation is in flight. */
+        isPending: boolean;
+        /** Always `'create'`; the hook always submits as a signing operation. */
+        mode: 'create';
+    };
+    /** Imperative actions exposed by the hook. */
+    actions: {
+        /** Validates the form and submits the signature. Resolves with the signed document on success, or `undefined` on validation or API failure. */
+        onSubmit: () => Promise<HookSubmitResult<DocumentSigned> | undefined>;
+    };
+}
+/**
+ * Result of {@link useContractorSignatureForm} — a discriminated union on `isLoading`.
+ *
+ * @public
+ */
+export type UseContractorSignatureFormResult = HookLoadingResult | UseContractorSignatureFormReady;
+/**
+ * Per-field metadata exposed by {@link useContractorSignatureForm} as `form.fieldsMetadata`.
+ *
+ * @remarks
+ * Extracted from the ready-state result for standalone use when a partner needs
+ * to type-check or reference the metadata shape independently.
+ *
+ * @public
+ */
+export type ContractorSignatureFieldsMetadata = { name: FieldMetadata; businessName: FieldMetadata; taxClassification: import("../../../../../partner-hook-utils/types").FieldMetadataWithOptions<"other" | "individual_proprietor" | "c_corporation" | "s_corporation" | "partnership" | "trust_estate" | "limited_liability_company">; llcClassificationCode: import("../../../../../partner-hook-utils/types").FieldMetadataWithOptions<"c" | "s" | "p">; otherText: FieldMetadata; foreignPartners: FieldMetadata; exemptPayeeCode: FieldMetadata; exemptionFromFatca: FieldMetadata; homeAddressStreet1: FieldMetadata; homeAddressStreet2: FieldMetadata; homeAddressCity: FieldMetadata; homeAddressState: FieldMetadata; homeAddressZip: FieldMetadata; accountNumber: FieldMetadata; companyName: FieldMetadata; ssn: FieldMetadata; ein: FieldMetadata; signatureText: FieldMetadata; agree: FieldMetadata; };
+/**
+ * Headless hook for signing a contractor document — collects the document's
+ * fields plus a typed signature and consent.
+ *
+ * @remarks
+ * This hook implements the W-9 — the only signable contractor document the API
+ * exposes today (`taxpayer_identification_form_w_9`). The field surface is
+ * declared statically (`form.Fields`), like the other SDK form hooks: core
+ * fields are always present, while variable fields are exposed only when the API
+ * returns them (otherwise `undefined`) — a presence-based safety check, so a
+ * field the API drops is skipped rather than rendered as an orphan. The seven
+ * federal tax-classification checkboxes are collapsed into a single required
+ * radio group with conditional LLC-code and "Other" sub-fields, and on submit
+ * the selection is mapped back to the W-9 wire format. Pre-filled values (name,
+ * address, TIN, etc.) are editable inputs; the signing `date` is omitted so the
+ * API auto-fills it. A document that returns no recognized W-9 fields renders
+ * as acknowledge-only (`data.hasFields` is `false`). Consult
+ * `form.fieldsMetadata` for per-field required flags and select/radio options.
+ *
+ * @param props - See {@link UseContractorSignatureFormProps}.
+ * @returns A {@link HookLoadingResult} while loading, or a {@link UseContractorSignatureFormReady} once loaded.
+ * @public
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   useContractorSignatureForm,
+ *   SDKFormProvider,
+ *   type UseContractorSignatureFormReady,
+ * } from '@gusto/embedded-react-sdk'
+ *
+ * function SignDocumentPage({ documentId }: { documentId: string }) {
+ *   const signatureForm = useContractorSignatureForm({ documentId })
+ *
+ *   if (signatureForm.isLoading) return <div>Loading...</div>
+ *
+ *   return <SignDocumentReady signatureForm={signatureForm} />
+ * }
+ *
+ * function SignDocumentReady({
+ *   signatureForm,
+ * }: {
+ *   signatureForm: UseContractorSignatureFormReady
+ * }) {
+ *   const { Fields } = signatureForm.form
+ *
+ *   const handleSubmit = async () => {
+ *     await signatureForm.actions.onSubmit()
+ *   }
+ *
+ *   return (
+ *     <SDKFormProvider {...signatureForm.form.methods}>
+ *       {Fields.Name ? <Fields.Name /> : null}
+ *       {Fields.SignatureText ? <Fields.SignatureText /> : null}
+ *       <Fields.Agree />
+ *       <button onClick={handleSubmit}>Sign</button>
+ *     </SDKFormProvider>
+ *   )
+ * }
+ * ```
+ */
+export declare function useContractorSignatureForm({ documentUuid, validationMode, shouldFocusError, optionalFieldsToRequire, }: UseContractorSignatureFormProps): UseContractorSignatureFormResult;
+export {};

package/dist/components/Contractor/Documents/SignatureForm/useContractorSignatureForm/useContractorSignatureForm.js

@@ -0,0 +1,182 @@
+import { useMemo as i } from "react";
+import { useForm as M, useWatch as N } from "react-hook-form";
+import { zodResolver as B } from "@hookform/resolvers/zod";
+import { useContractorDocumentsGet as Z } from "@gusto/embedded-api-v-2026-02-01/react-query/contractorDocumentsGet";
+import { useContractorDocumentsGetPdf as V } from "@gusto/embedded-api-v-2026-02-01/react-query/contractorDocumentsGetPdf";
+import { useContractorDocumentsSignMutation as W } from "@gusto/embedded-api-v-2026-02-01/react-query/contractorDocumentsSign";
+import { getPresentFieldNames as z, getRedactionState as G, EMPTY_W9_DEFAULTS as k, buildW9Defaults as K, OTHER_CLASSIFICATION_OPTION as Q, LLC_CLASSIFICATION_OPTION as Y, serializeW9Fields as q, LLC_CLASSIFICATION_CODES as x, TAX_CLASSIFICATION_OPTION_KEYS as v } from "./w9Fields.js";
+import { createContractorSignatureFormSchema as U } from "./contractorSignatureFormSchema.js";
+import { CompanyNameField as X, AccountNumberField as j, HomeAddressStreet2Field as J, ExemptionFromFatcaField as $, ExemptPayeeCodeField as ee, ForeignPartnersField as te, OtherTextField as oe, LlcClassificationCodeField as re, BusinessNameField as se, AgreeField as ie, SignatureTextField as ae, EinField as ne, SsnField as de, HomeAddressZipField as me, HomeAddressStateField as ce, HomeAddressCityField as ue, HomeAddressStreet1Field as le, TaxClassificationField as fe, NameField as he } from "./fields.js";
+import { useDeriveFieldsMetadata as Ce } from "../../../../../partner-hook-utils/form/useDeriveFieldsMetadata.js";
+import { withOptions as y } from "../../../../../partner-hook-utils/form/withOptions.js";
+import { withFlags as P } from "../../../../../partner-hook-utils/form/withFlags.js";
+import { useHookFormInternals as Se } from "../../../../../partner-hook-utils/form/useHookFormInternals.js";
+import { createGetFormSubmissionValues as Ae } from "../../../../../partner-hook-utils/form/getFormSubmissionValues.js";
+import { composeErrorHandler as ge } from "../../../../../partner-hook-utils/composeErrorHandler.js";
+import { useBaseSubmit as Fe } from "../../../../Base/useBaseSubmit.js";
+import { SDKInternalError as T } from "../../../../../types/sdkError.js";
+function pe(e, r) {
+  return {
+    // Every field is presence-gated to guard against the document API diverging
+    // (dropping or renaming a field) — only `Agree` is synthesized and always on.
+    Name: e.has("name") ? he : void 0,
+    TaxClassification: e.has("taxClassification") ? fe : void 0,
+    HomeAddressStreet1: e.has("homeAddressStreet1") ? le : void 0,
+    HomeAddressCity: e.has("homeAddressCity") ? ue : void 0,
+    HomeAddressState: e.has("homeAddressState") ? ce : void 0,
+    HomeAddressZip: e.has("homeAddressZip") ? me : void 0,
+    Ssn: e.has("ssn") ? de : void 0,
+    Ein: e.has("ein") ? ne : void 0,
+    SignatureText: e.has("signatureText") ? ae : void 0,
+    Agree: ie,
+    BusinessName: e.has("businessName") ? se : void 0,
+    // Revealed only while the LLC classification is selected (and the document
+    // carries classification checkboxes).
+    LlcClassificationCode: e.has("llcClassificationCode") && r === Y ? re : void 0,
+    // Revealed only while the "Other" classification is selected.
+    OtherText: e.has("otherText") && r === Q ? oe : void 0,
+    ForeignPartners: e.has("foreignPartners") ? te : void 0,
+    ExemptPayeeCode: e.has("exemptPayeeCode") ? ee : void 0,
+    ExemptionFromFatca: e.has("exemptionFromFatca") ? $ : void 0,
+    HomeAddressStreet2: e.has("homeAddressStreet2") ? J : void 0,
+    AccountNumber: e.has("accountNumber") ? j : void 0,
+    CompanyName: e.has("companyName") ? X : void 0
+  };
+}
+function xe(e, { ssnPlaceholder: r, einPlaceholder: d }) {
+  const m = v.map((s) => ({
+    value: s,
+    label: s
+  })), a = x.map((s) => ({
+    value: s,
+    label: s
+  }));
+  return {
+    name: e.name,
+    businessName: e.businessName,
+    taxClassification: y(e.taxClassification, m, [
+      ...v
+    ]),
+    llcClassificationCode: y(e.llcClassificationCode, a, [
+      ...x
+    ]),
+    otherText: e.otherText,
+    foreignPartners: e.foreignPartners,
+    exemptPayeeCode: e.exemptPayeeCode,
+    exemptionFromFatca: e.exemptionFromFatca,
+    homeAddressStreet1: e.homeAddressStreet1,
+    homeAddressStreet2: e.homeAddressStreet2,
+    homeAddressCity: e.homeAddressCity,
+    homeAddressState: e.homeAddressState,
+    homeAddressZip: e.homeAddressZip,
+    accountNumber: e.accountNumber,
+    companyName: e.companyName,
+    // The masked value drives the redacted SSN/EIN placeholder. `buildFormSchema`
+    // already set `hasRedactedValue` and exempted the field from required validation.
+    ssn: P(e.ssn, r ? { placeholder: r } : {}),
+    ein: P(e.ein, d ? { placeholder: d } : {}),
+    signatureText: e.signatureText,
+    agree: e.agree
+  };
+}
+function Ve({
+  documentUuid: e,
+  validationMode: r = "onSubmit",
+  shouldFocusError: d = !0,
+  optionalFieldsToRequire: m
+}) {
+  const a = Z({ documentUuid: e }), s = V({ documentUuid: e }), t = a.data?.document, c = i(
+    () => t ? z(t) : /* @__PURE__ */ new Set(),
+    [t]
+  ), o = i(
+    () => t ? G(t) : { ssnRedacted: !1, einRedacted: !1 },
+    [t]
+  ), [u, I] = i(
+    () => U({
+      optionalFieldsToRequire: m,
+      ssnRedacted: o.ssnRedacted,
+      einRedacted: o.einRedacted
+    }),
+    [m, o.ssnRedacted, o.einRedacted]
+  ), l = i(
+    () => t ? K(t) : k,
+    [t]
+  ), n = M(
+    {
+      resolver: B(u),
+      mode: r,
+      shouldFocusError: d,
+      defaultValues: l,
+      values: l,
+      resetOptions: { keepDirtyValues: !0 }
+    }
+  ), f = N({
+    control: n.control,
+    name: "taxClassification"
+  }), O = i(
+    () => pe(c, f),
+    [c, f]
+  ), h = Ce(I, n.control), E = i(
+    () => xe(h, {
+      ssnPlaceholder: o.ssnPlaceholder,
+      einPlaceholder: o.einPlaceholder
+    }),
+    [h, o]
+  ), C = W(), H = C.isPending, {
+    baseSubmitHandler: L,
+    error: w,
+    setError: D
+  } = Fe("ContractorSignatureForm"), S = ge([a], { submitError: w, setSubmitError: D }), R = async () => {
+    let A;
+    return await new Promise((g) => {
+      n.handleSubmit(
+        async (b) => {
+          await L(b, async (F) => {
+            if (!t)
+              throw new T("Document must be loaded before signing");
+            const p = (await C.mutateAsync({
+              request: {
+                documentUuid: e,
+                requestBody: {
+                  fields: q(t, F, o),
+                  agree: F.agree,
+                  // The signing IP is supplied by the partner proxy via the
+                  // `x-gusto-client-ip` header; send an empty body value to
+                  // match the employee/company sign flows.
+                  signedByIpAddress: ""
+                }
+              }
+            })).documentSigned;
+            if (!p)
+              throw new T("Contractor document signing failed");
+            A = { mode: "create", data: p };
+          }), g();
+        },
+        () => {
+          g();
+        }
+      )();
+    }), A;
+  }, _ = Se(n);
+  return a.isLoading || !t ? { isLoading: !0, errorHandling: S } : {
+    isLoading: !1,
+    data: {
+      document: t,
+      pdfUrl: s.data?.documentPdf?.documentUrl ?? null,
+      hasFields: c.size > 0
+    },
+    status: { isPending: H, mode: "create" },
+    actions: { onSubmit: R },
+    errorHandling: S,
+    form: {
+      Fields: O,
+      fieldsMetadata: E,
+      hookFormInternals: _,
+      getFormSubmissionValues: Ae(n, u)
+    }
+  };
+}
+export {
+  Ve as useContractorSignatureForm
+};
+//# sourceMappingURL=useContractorSignatureForm.js.map

package/dist/components/Contractor/Documents/SignatureForm/useContractorSignatureForm/useContractorSignatureForm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useContractorSignatureForm.js","sources":["../../../../../../src/components/Contractor/Documents/SignatureForm/useContractorSignatureForm/useContractorSignatureForm.tsx"],"sourcesContent":["import { useMemo } from 'react'\nimport { useForm, useWatch } from 'react-hook-form'\nimport type { UseFormProps } from 'react-hook-form'\nimport { zodResolver } from '@hookform/resolvers/zod'\nimport type { Document } from '@gusto/embedded-api-v-2026-02-01/models/components/document'\nimport type { DocumentSigned } from '@gusto/embedded-api-v-2026-02-01/models/components/documentsigned'\nimport { useContractorDocumentsGet } from '@gusto/embedded-api-v-2026-02-01/react-query/contractorDocumentsGet'\nimport { useContractorDocumentsGetPdf } from '@gusto/embedded-api-v-2026-02-01/react-query/contractorDocumentsGetPdf'\nimport { useContractorDocumentsSignMutation } from '@gusto/embedded-api-v-2026-02-01/react-query/contractorDocumentsSign'\nimport {\n  buildW9Defaults,\n  getPresentFieldNames,\n  getRedactionState,\n  serializeW9Fields,\n  EMPTY_W9_DEFAULTS,\n  TAX_CLASSIFICATION_OPTION_KEYS,\n  LLC_CLASSIFICATION_CODES,\n  LLC_CLASSIFICATION_OPTION,\n  OTHER_CLASSIFICATION_OPTION,\n  type W9RedactionState,\n} from './w9Fields'\nimport {\n  createContractorSignatureFormSchema,\n  type ContractorSignatureFormData,\n  type ContractorSignatureFormOutputs,\n  type ContractorSignatureOptionalFieldsToRequire,\n} from './contractorSignatureFormSchema'\nimport {\n  NameField,\n  TaxClassificationField,\n  HomeAddressStreet1Field,\n  HomeAddressCityField,\n  HomeAddressStateField,\n  HomeAddressZipField,\n  SsnField,\n  EinField,\n  SignatureTextField,\n  AgreeField,\n  BusinessNameField,\n  LlcClassificationCodeField,\n  OtherTextField,\n  ForeignPartnersField,\n  ExemptPayeeCodeField,\n  ExemptionFromFatcaField,\n  HomeAddressStreet2Field,\n  AccountNumberField,\n  CompanyNameField,\n  type ContractorSignatureFormFieldComponents,\n} from './fields'\nimport { useDeriveFieldsMetadata } from '@/partner-hook-utils/form/useDeriveFieldsMetadata'\nimport { withOptions } from '@/partner-hook-utils/form/withOptions'\nimport { withFlags } from '@/partner-hook-utils/form/withFlags'\nimport { useHookFormInternals } from '@/partner-hook-utils/form/useHookFormInternals'\nimport { createGetFormSubmissionValues } from '@/partner-hook-utils/form/getFormSubmissionValues'\nimport { composeErrorHandler } from '@/partner-hook-utils/composeErrorHandler'\nimport type {\n  BaseFormHookReady,\n  FieldMetadata,\n  FieldsMetadata,\n  HookLoadingResult,\n  HookSubmitResult,\n} from '@/partner-hook-utils/types'\nimport { useBaseSubmit } from '@/components/Base/useBaseSubmit'\nimport { SDKInternalError } from '@/types/sdkError'\n\n/**\n * Props for {@link useContractorSignatureForm}.\n *\n * @public\n */\nexport interface UseContractorSignatureFormProps {\n  /** UUID of the contractor document to sign. */\n  documentUuid: string\n  /** When validation runs. Passed through to react-hook-form; defaults to `'onSubmit'`. */\n  validationMode?: UseFormProps['mode']\n  /** Auto-focus the first invalid field on submit. Defaults to `true`; set to `false` when using `composeSubmitHandler`. */\n  shouldFocusError?: boolean\n  /** Promote optional W-9 fields to required (e.g. `{ create: ['businessName'] }`). */\n  optionalFieldsToRequire?: ContractorSignatureOptionalFieldsToRequire\n}\n\n/**\n * Ready-state shape returned by {@link useContractorSignatureForm} once the\n * document metadata has loaded.\n *\n * @public\n */\nexport interface UseContractorSignatureFormReady extends BaseFormHookReady<\n  ContractorSignatureFieldsMetadata,\n  ContractorSignatureFormData,\n  ContractorSignatureFormFieldComponents\n> {\n  /** Loaded data — the document being signed and a downloadable PDF URL. */\n  data: {\n    /** The document entity fetched from the API. */\n    document: Document\n    /** URL to the document's PDF, or `null` when unavailable. */\n    pdfUrl: string | null\n    /** Whether the document carries signable fields (vs. acknowledge-only). */\n    hasFields: boolean\n  }\n  /** Submit-state flags. */\n  status: {\n    /** `true` while the sign mutation is in flight. */\n    isPending: boolean\n    /** Always `'create'`; the hook always submits as a signing operation. */\n    mode: 'create'\n  }\n  /** Imperative actions exposed by the hook. */\n  actions: {\n    /** Validates the form and submits the signature. Resolves with the signed document on success, or `undefined` on validation or API failure. */\n    onSubmit: () => Promise<HookSubmitResult<DocumentSigned> | undefined>\n  }\n}\n\n/**\n * Result of {@link useContractorSignatureForm} — a discriminated union on `isLoading`.\n *\n * @public\n */\nexport type UseContractorSignatureFormResult = HookLoadingResult | UseContractorSignatureFormReady\n\n/**\n * Per-field metadata exposed by {@link useContractorSignatureForm} as `form.fieldsMetadata`.\n *\n * @remarks\n * Extracted from the ready-state result for standalone use when a partner needs\n * to type-check or reference the metadata shape independently.\n *\n * @public\n */\nexport type ContractorSignatureFieldsMetadata = ReturnType<\n  typeof buildContractorSignatureFieldsMetadata\n>\n\nfunction buildFields(\n  presentFieldNames: Set<string>,\n  classification: string,\n): ContractorSignatureFormFieldComponents {\n  return {\n    // Every field is presence-gated to guard against the document API diverging\n    // (dropping or renaming a field) — only `Agree` is synthesized and always on.\n    Name: presentFieldNames.has('name') ? NameField : undefined,\n    TaxClassification: presentFieldNames.has('taxClassification')\n      ? TaxClassificationField\n      : undefined,\n    HomeAddressStreet1: presentFieldNames.has('homeAddressStreet1')\n      ? HomeAddressStreet1Field\n      : undefined,\n    HomeAddressCity: presentFieldNames.has('homeAddressCity') ? HomeAddressCityField : undefined,\n    HomeAddressState: presentFieldNames.has('homeAddressState') ? HomeAddressStateField : undefined,\n    HomeAddressZip: presentFieldNames.has('homeAddressZip') ? HomeAddressZipField : undefined,\n    Ssn: presentFieldNames.has('ssn') ? SsnField : undefined,\n    Ein: presentFieldNames.has('ein') ? EinField : undefined,\n    SignatureText: presentFieldNames.has('signatureText') ? SignatureTextField : undefined,\n    Agree: AgreeField,\n    BusinessName: presentFieldNames.has('businessName') ? BusinessNameField : undefined,\n    // Revealed only while the LLC classification is selected (and the document\n    // carries classification checkboxes).\n    LlcClassificationCode:\n      presentFieldNames.has('llcClassificationCode') && classification === LLC_CLASSIFICATION_OPTION\n        ? LlcClassificationCodeField\n        : undefined,\n    // Revealed only while the \"Other\" classification is selected.\n    OtherText:\n      presentFieldNames.has('otherText') && classification === OTHER_CLASSIFICATION_OPTION\n        ? OtherTextField\n        : undefined,\n    ForeignPartners: presentFieldNames.has('foreignPartners') ? ForeignPartnersField : undefined,\n    ExemptPayeeCode: presentFieldNames.has('exemptPayeeCode') ? ExemptPayeeCodeField : undefined,\n    ExemptionFromFatca: presentFieldNames.has('exemptionFromFatca')\n      ? ExemptionFromFatcaField\n      : undefined,\n    HomeAddressStreet2: presentFieldNames.has('homeAddressStreet2')\n      ? HomeAddressStreet2Field\n      : undefined,\n    AccountNumber: presentFieldNames.has('accountNumber') ? AccountNumberField : undefined,\n    CompanyName: presentFieldNames.has('companyName') ? CompanyNameField : undefined,\n  }\n}\n\n/** @internal */\nfunction buildContractorSignatureFieldsMetadata(\n  base: Record<keyof ContractorSignatureFormData, FieldMetadata>,\n  { ssnPlaceholder, einPlaceholder }: { ssnPlaceholder?: string; einPlaceholder?: string },\n) {\n  const taxClassificationOptions = TAX_CLASSIFICATION_OPTION_KEYS.map(key => ({\n    value: key,\n    label: key,\n  }))\n  const llcClassificationOptions = LLC_CLASSIFICATION_CODES.map(code => ({\n    value: code,\n    label: code,\n  }))\n\n  return {\n    name: base.name,\n    businessName: base.businessName,\n    taxClassification: withOptions(base.taxClassification, taxClassificationOptions, [\n      ...TAX_CLASSIFICATION_OPTION_KEYS,\n    ]),\n    llcClassificationCode: withOptions(base.llcClassificationCode, llcClassificationOptions, [\n      ...LLC_CLASSIFICATION_CODES,\n    ]),\n    otherText: base.otherText,\n    foreignPartners: base.foreignPartners,\n    exemptPayeeCode: base.exemptPayeeCode,\n    exemptionFromFatca: base.exemptionFromFatca,\n    homeAddressStreet1: base.homeAddressStreet1,\n    homeAddressStreet2: base.homeAddressStreet2,\n    homeAddressCity: base.homeAddressCity,\n    homeAddressState: base.homeAddressState,\n    homeAddressZip: base.homeAddressZip,\n    accountNumber: base.accountNumber,\n    companyName: base.companyName,\n    // The masked value drives the redacted SSN/EIN placeholder. `buildFormSchema`\n    // already set `hasRedactedValue` and exempted the field from required validation.\n    ssn: withFlags(base.ssn, ssnPlaceholder ? { placeholder: ssnPlaceholder } : {}),\n    ein: withFlags(base.ein, einPlaceholder ? { placeholder: einPlaceholder } : {}),\n    signatureText: base.signatureText,\n    agree: base.agree,\n  } satisfies FieldsMetadata\n}\n\n/**\n * Headless hook for signing a contractor document — collects the document's\n * fields plus a typed signature and consent.\n *\n * @remarks\n * This hook implements the W-9 — the only signable contractor document the API\n * exposes today (`taxpayer_identification_form_w_9`). The field surface is\n * declared statically (`form.Fields`), like the other SDK form hooks: core\n * fields are always present, while variable fields are exposed only when the API\n * returns them (otherwise `undefined`) — a presence-based safety check, so a\n * field the API drops is skipped rather than rendered as an orphan. The seven\n * federal tax-classification checkboxes are collapsed into a single required\n * radio group with conditional LLC-code and \"Other\" sub-fields, and on submit\n * the selection is mapped back to the W-9 wire format. Pre-filled values (name,\n * address, TIN, etc.) are editable inputs; the signing `date` is omitted so the\n * API auto-fills it. A document that returns no recognized W-9 fields renders\n * as acknowledge-only (`data.hasFields` is `false`). Consult\n * `form.fieldsMetadata` for per-field required flags and select/radio options.\n *\n * @param props - See {@link UseContractorSignatureFormProps}.\n * @returns A {@link HookLoadingResult} while loading, or a {@link UseContractorSignatureFormReady} once loaded.\n * @public\n *\n * @example\n * ```tsx\n * import {\n *   useContractorSignatureForm,\n *   SDKFormProvider,\n *   type UseContractorSignatureFormReady,\n * } from '@gusto/embedded-react-sdk'\n *\n * function SignDocumentPage({ documentId }: { documentId: string }) {\n *   const signatureForm = useContractorSignatureForm({ documentId })\n *\n *   if (signatureForm.isLoading) return <div>Loading...</div>\n *\n *   return <SignDocumentReady signatureForm={signatureForm} />\n * }\n *\n * function SignDocumentReady({\n *   signatureForm,\n * }: {\n *   signatureForm: UseContractorSignatureFormReady\n * }) {\n *   const { Fields } = signatureForm.form\n *\n *   const handleSubmit = async () => {\n *     await signatureForm.actions.onSubmit()\n *   }\n *\n *   return (\n *     <SDKFormProvider {...signatureForm.form.methods}>\n *       {Fields.Name ? <Fields.Name /> : null}\n *       {Fields.SignatureText ? <Fields.SignatureText /> : null}\n *       <Fields.Agree />\n *       <button onClick={handleSubmit}>Sign</button>\n *     </SDKFormProvider>\n *   )\n * }\n * ```\n */\nexport function useContractorSignatureForm({\n  documentUuid,\n  validationMode = 'onSubmit',\n  shouldFocusError = true,\n  optionalFieldsToRequire,\n}: UseContractorSignatureFormProps): UseContractorSignatureFormResult {\n  const documentQuery = useContractorDocumentsGet({ documentUuid })\n  // PDF failures are intentionally excluded from the page error surface; the\n  // download link is simply hidden when the URL is unavailable.\n  const pdfQuery = useContractorDocumentsGetPdf({ documentUuid })\n\n  const document = documentQuery.data?.document\n\n  const presentFieldNames = useMemo(\n    () => (document ? getPresentFieldNames(document) : new Set<string>()),\n    [document],\n  )\n  const redaction = useMemo<W9RedactionState>(\n    () => (document ? getRedactionState(document) : { ssnRedacted: false, einRedacted: false }),\n    [document],\n  )\n\n  const [schema, metadataConfig] = useMemo(\n    () =>\n      createContractorSignatureFormSchema({\n        optionalFieldsToRequire,\n        ssnRedacted: redaction.ssnRedacted,\n        einRedacted: redaction.einRedacted,\n      }),\n    [optionalFieldsToRequire, redaction.ssnRedacted, redaction.einRedacted],\n  )\n\n  const defaultValues = useMemo<ContractorSignatureFormData>(\n    () => (document ? buildW9Defaults(document) : EMPTY_W9_DEFAULTS),\n    [document],\n  )\n\n  const formMethods = useForm<ContractorSignatureFormData, unknown, ContractorSignatureFormOutputs>(\n    {\n      resolver: zodResolver(schema),\n      mode: validationMode,\n      shouldFocusError,\n      defaultValues,\n      values: defaultValues,\n      resetOptions: { keepDirtyValues: true },\n    },\n  )\n\n  const watchedClassification = useWatch({\n    control: formMethods.control,\n    name: 'taxClassification',\n  })\n  const Fields = useMemo(\n    () => buildFields(presentFieldNames, watchedClassification),\n    [presentFieldNames, watchedClassification],\n  )\n\n  const baseMetadata = useDeriveFieldsMetadata(metadataConfig, formMethods.control)\n\n  const fieldsMetadata = useMemo(\n    () =>\n      buildContractorSignatureFieldsMetadata(baseMetadata, {\n        ssnPlaceholder: redaction.ssnPlaceholder,\n        einPlaceholder: redaction.einPlaceholder,\n      }),\n    [baseMetadata, redaction],\n  )\n\n  const signMutation = useContractorDocumentsSignMutation()\n  const isPending = signMutation.isPending\n\n  const {\n    baseSubmitHandler,\n    error: submitError,\n    setError: setSubmitError,\n  } = useBaseSubmit('ContractorSignatureForm')\n\n  const errorHandling = composeErrorHandler([documentQuery], { submitError, setSubmitError })\n\n  const onSubmit = async (): Promise<HookSubmitResult<DocumentSigned> | undefined> => {\n    let submitResult: HookSubmitResult<DocumentSigned> | undefined\n\n    await new Promise<void>(resolve => {\n      void formMethods.handleSubmit(\n        async (data: ContractorSignatureFormOutputs) => {\n          await baseSubmitHandler(data, async payload => {\n            if (!document) {\n              throw new SDKInternalError('Document must be loaded before signing')\n            }\n\n            const result = await signMutation.mutateAsync({\n              request: {\n                documentUuid,\n                requestBody: {\n                  fields: serializeW9Fields(document, payload, redaction),\n                  agree: payload.agree,\n                  // The signing IP is supplied by the partner proxy via the\n                  // `x-gusto-client-ip` header; send an empty body value to\n                  // match the employee/company sign flows.\n                  signedByIpAddress: '',\n                },\n              },\n            })\n\n            const signedDocument = result.documentSigned\n\n            if (!signedDocument) {\n              throw new SDKInternalError('Contractor document signing failed')\n            }\n\n            submitResult = { mode: 'create', data: signedDocument }\n          })\n          resolve()\n        },\n        () => {\n          resolve()\n        },\n      )()\n    })\n\n    return submitResult\n  }\n\n  const hookFormInternals = useHookFormInternals(formMethods)\n\n  if (documentQuery.isLoading || !document) {\n    return { isLoading: true, errorHandling }\n  }\n\n  return {\n    isLoading: false,\n    data: {\n      document,\n      pdfUrl: pdfQuery.data?.documentPdf?.documentUrl ?? null,\n      hasFields: presentFieldNames.size > 0,\n    },\n    status: { isPending, mode: 'create' },\n    actions: { onSubmit },\n    errorHandling,\n    form: {\n      Fields,\n      fieldsMetadata,\n      hookFormInternals,\n      getFormSubmissionValues: createGetFormSubmissionValues(formMethods, schema),\n    },\n  }\n}\n"],"names":["buildFields","presentFieldNames","classification","NameField","TaxClassificationField","HomeAddressStreet1Field","HomeAddressCityField","HomeAddressStateField","HomeAddressZipField","SsnField","EinField","SignatureTextField","AgreeField","BusinessNameField","LLC_CLASSIFICATION_OPTION","LlcClassificationCodeField","OTHER_CLASSIFICATION_OPTION","OtherTextField","ForeignPartnersField","ExemptPayeeCodeField","ExemptionFromFatcaField","HomeAddressStreet2Field","AccountNumberField","CompanyNameField","buildContractorSignatureFieldsMetadata","base","ssnPlaceholder","einPlaceholder","taxClassificationOptions","TAX_CLASSIFICATION_OPTION_KEYS","key","llcClassificationOptions","LLC_CLASSIFICATION_CODES","code","withOptions","withFlags","useContractorSignatureForm","documentUuid","validationMode","shouldFocusError","optionalFieldsToRequire","documentQuery","useContractorDocumentsGet","pdfQuery","useContractorDocumentsGetPdf","document","useMemo","getPresentFieldNames","redaction","getRedactionState","schema","metadataConfig","createContractorSignatureFormSchema","defaultValues","buildW9Defaults","EMPTY_W9_DEFAULTS","formMethods","useForm","zodResolver","watchedClassification","useWatch","Fields","baseMetadata","useDeriveFieldsMetadata","fieldsMetadata","signMutation","useContractorDocumentsSignMutation","isPending","baseSubmitHandler","submitError","setSubmitError","useBaseSubmit","errorHandling","composeErrorHandler","onSubmit","submitResult","resolve","data","payload","SDKInternalError","signedDocument","serializeW9Fields","hookFormInternals","useHookFormInternals","createGetFormSubmissionValues"],"mappings":"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"}

package/dist/components/Contractor/Documents/SignatureForm/useContractorSignatureForm/w9Fields.d.ts

@@ -0,0 +1,223 @@
+import { Document } from '@gusto/embedded-api-v-2026-02-01/models/components/document';
+import { ContractorSignatureFormData } from './contractorSignatureFormSchema';
+/**
+ * The `name` of the W-9 document — the only contractor document type that
+ * supports signing today.
+ *
+ * @internal
+ */
+export declare const W9_DOCUMENT_NAME = "taxpayer_identification_form_w_9";
+/**
+ * Sentinel the API returns (and accepts) for a taxpayer-ID field that doesn't
+ * apply to the signer — e.g. the EIN of an individual contractor, or the SSN of
+ * a business contractor. The sign endpoint stamps this verbatim, so the form
+ * both prefills it and treats it as a valid submission.
+ *
+ * @internal
+ */
+export declare const NOT_APPLICABLE_VALUE = "N/A";
+/**
+ * EIN input transform that preserves the `N/A` sentinel (and the in-progress
+ * prefixes a user types toward it) while formatting numeric input as a standard
+ * EIN (`NN-NNNNNNN`).
+ *
+ * @remarks
+ * The W-9 accepts `N/A` for a taxpayer who supplies an SSN instead of an EIN,
+ * but the plain `normalizeEin` formatter strips every non-digit on each
+ * keystroke — making the sentinel impossible to type. This wrapper lets the
+ * sentinel through (normalized to uppercase) and defers to `normalizeEin` for
+ * everything else.
+ *
+ * @param value - Raw user input.
+ * @returns The `N/A` sentinel (or an in-progress prefix), otherwise the EIN-formatted value.
+ * @internal
+ */
+export declare function normalizeEinOrNotApplicable(value: string): string;
+/**
+ * SSN input transform that preserves the `N/A` sentinel (and the in-progress
+ * prefixes `N` and `N/`) while otherwise deferring to {@link normalizeSSN}.
+ *
+ * @remarks
+ * The W-9 accepts `N/A` for a taxpayer who supplies an EIN instead of an SSN,
+ * but the plain `normalizeSSN` formatter strips every non-digit on each
+ * keystroke — making the sentinel impossible to type. This wrapper lets the
+ * sentinel through (normalized to uppercase) and defers to `normalizeSSN` for
+ * everything else.
+ *
+ * @param value - Raw user input.
+ * @returns The `N/A` sentinel (or an in-progress prefix), otherwise the SSN-formatted value.
+ * @internal
+ */
+export declare function normalizeSsnOrNotApplicable(value: string): string;
+/**
+ * Form-field name for the synthesized federal tax classification radio group.
+ *
+ * @internal
+ */
+export declare const TAX_CLASSIFICATION_FIELD = "taxClassification";
+/**
+ * Form-field name for the synthesized LLC tax classification code select.
+ *
+ * @internal
+ */
+export declare const LLC_CLASSIFICATION_FIELD = "llcClassificationCode";
+/**
+ * Form-field name for the "Other" free-text classification field.
+ *
+ * @internal
+ */
+export declare const OTHER_TEXT_FIELD = "otherText";
+/**
+ * Ordered classification option keys backing the {@link TAX_CLASSIFICATION_FIELD}
+ * radio group. Each maps to a W-9 checkbox field on the underlying document.
+ *
+ * @internal
+ */
+export declare const TAX_CLASSIFICATION_OPTION_KEYS: readonly ["individual_proprietor", "c_corporation", "s_corporation", "partnership", "trust_estate", "limited_liability_company", "other"];
+/**
+ * A single federal tax classification option key.
+ *
+ * @internal
+ */
+export type TaxClassificationOptionKey = (typeof TAX_CLASSIFICATION_OPTION_KEYS)[number];
+/**
+ * The classification option that reveals the LLC tax classification select.
+ *
+ * @internal
+ */
+export declare const LLC_CLASSIFICATION_OPTION: TaxClassificationOptionKey;
+/**
+ * The classification option that reveals the "Other" free-text field.
+ *
+ * @internal
+ */
+export declare const OTHER_CLASSIFICATION_OPTION: TaxClassificationOptionKey;
+/**
+ * Ordered LLC tax classification code options.
+ *
+ * @internal
+ */
+export declare const LLC_CLASSIFICATION_CODES: readonly ["c", "s", "p"];
+/**
+ * Maps each pass-through {@link ContractorSignatureFormData} field to its W-9
+ * API field key. Synthesized fields (`taxClassification`,
+ * `llcClassificationCode`) and `agree` are intentionally absent.
+ *
+ * @internal
+ */
+export declare const W9_FIELD_API_KEYS: {
+    readonly name: "name";
+    readonly businessName: "business_name";
+    readonly otherText: "other_text";
+    readonly foreignPartners: "foreign_partners";
+    readonly exemptPayeeCode: "exempt_payee_code";
+    readonly exemptionFromFatca: "exemption_from_FATCA";
+    readonly homeAddressStreet1: "home_address_street_1";
+    readonly homeAddressStreet2: "home_address_street_2";
+    readonly homeAddressCity: "home_address_city";
+    readonly homeAddressState: "home_address_state";
+    readonly homeAddressZip: "home_address_zip";
+    readonly accountNumber: "account_number";
+    readonly companyName: "company_name";
+    readonly ssn: "ssn";
+    readonly ein: "ein";
+    readonly signatureText: "signature_text";
+};
+/**
+ * Whether the document is a W-9 (the only signable contractor document type).
+ *
+ * @internal
+ */
+export declare function isW9Document(document: Document): boolean;
+/**
+ * Redaction state for the sensitive W-9 fields, derived from the API response.
+ *
+ * @internal
+ */
+export interface W9RedactionState {
+    /** Whether the API returned a masked SSN value. */
+    ssnRedacted: boolean;
+    /** Whether the API returned a masked EIN value. */
+    einRedacted: boolean;
+    /** The masked SSN to surface as a placeholder, when redacted. */
+    ssnPlaceholder?: string;
+    /** The masked EIN to surface as a placeholder, when redacted. */
+    einPlaceholder?: string;
+}
+/**
+ * Computes the redaction state of the SSN/EIN fields from the document.
+ *
+ * @param document - The W-9 document returned by the API.
+ * @returns The redaction flags and masked placeholders.
+ * @internal
+ */
+export declare function getRedactionState(document: Document): W9RedactionState;
+/**
+ * Computes which W-9 form fields the API actually returned — the safety check
+ * that drives presence-gating in {@link useContractorSignatureForm}.
+ *
+ * @remarks
+ * A pass-through field is present when its API key is in `document.fields`. The
+ * synthesized classification fields (`taxClassification`,
+ * `llcClassificationCode`) are present when the document carries any of the
+ * federal tax classification checkbox fields.
+ *
+ * @param document - The W-9 document returned by the API.
+ * @returns The set of present camelCase field names.
+ * @internal
+ */
+export declare function getPresentFieldNames(document: Document): Set<string>;
+/**
+ * Builds default form values from a document's fields.
+ *
+ * @remarks
+ * Pass-through values are seeded from the API `value`. The classification radio
+ * defaults to whichever classification checkbox is already set (`'1'`/`'true'`),
+ * and when that is the LLC classification the LLC code select is seeded from the
+ * `tax_classification` field it serializes into. A masked SSN/EIN seeds an empty
+ * input (the mask is surfaced as a placeholder instead) so it is never echoed
+ * back as the new value on submit.
+ *
+ * @param document - The W-9 document returned by the API.
+ * @returns The default form values.
+ * @internal
+ */
+export declare function buildW9Defaults(document: Document): ContractorSignatureFormData;
+/**
+ * The empty default form values, used while the document is still loading.
+ *
+ * @internal
+ */
+export declare const EMPTY_W9_DEFAULTS: ContractorSignatureFormData;
+/**
+ * A single `{ key, value }` pair sent in the sign request.
+ *
+ * @internal
+ */
+export interface SignFieldValue {
+    /** The API field key. */
+    key: string;
+    /** The serialized field value. */
+    value: string;
+}
+/**
+ * Serializes W-9 form values into the `{ key, value }` field array expected by
+ * the sign API.
+ *
+ * @remarks
+ * Only fields the API returned (see {@link getPresentFieldNames}) are sent.
+ * Applies the W-9 mapping: the chosen classification key is sent with value
+ * `'1'`; when the LLC classification is chosen, the selected LLC code is sent
+ * under the `tax_classification` key. `foreignPartners` serializes to
+ * `'1'`/`'0'`. The `otherText` value is only included for the "Other"
+ * classification. An untouched redacted SSN/EIN is omitted so the mask is never
+ * sent back. The `date` field is intentionally omitted so the API auto-fills the
+ * signing date in its own locale-correct format.
+ *
+ * @param document - The W-9 document being signed.
+ * @param values - The validated form values.
+ * @param redaction - The redaction state from {@link getRedactionState}.
+ * @returns The ordered field array for the sign request body.
+ * @internal
+ */
+export declare function serializeW9Fields(document: Document, values: ContractorSignatureFormData, redaction: W9RedactionState): SignFieldValue[];