@taxbit/react-sdk 1.0.0-beta.2 → 1.0.0-beta.4

package/README.md

@@ -1,6 +1,16 @@
 # Taxbit React SDK
 
-A React app, widget, and component for gathering Tax Documentation data for US and EU Tax forms.
+A React component and hook for gathering Tax Documentation data for US and EU Tax forms.
+
+## Usage
+
+The Taxbit React SDK provides a React component, hook, and Typescript types for gathering tax documentation data from users. The component can be used to collect data for the Taxbit DPS (Digital Platform Sales) or W-Form (W-9, W-8BEN, W-8BEN-E) tax documentation forms. A hook provides more tools to understand the user's tax documentation status and download any pdf versions of the files that are created if eligible.
+
+DPS (Digital Platform Sales) is a data standard and UI flow used by Taxbit to gather the information needed to report income as directed by the DAC7 for the European Union, and equivalent reporting requirements in Canada, New Zealand, and the United Kingdom.
+
+## Beta Stage
+
+During this stage, the Taxbit SDK is fully supported, and can be used in production environments. However, there may be breaking changes without a new major version release. If used in a production environment, Taxbit recommends setting a fixed version, updating regularly, and testing after each update.
 
 ## Installation
 
@@ -16,13 +26,13 @@ import { TaxbitQuestionnaire, ClientTaxDocumentation } from '@taxbit/react-sdk';
 ### Data
 
 ```typescript
-exampleData: ClientTaxDocumentation = {
+const exampleData: ClientTaxDocumentation = {
   accountHolder: {
     name: 'John Smith',
     tin: '456456456',
     ftin: '667788991',
-    usAccountType: 'individual',
-    foreignAccountType: 'individual',
+    usAccountType: 'INDIVIDUAL',
+    foreignAccountType: 'INDIVIDUAL',
     address: {
       firstLine: '123 Main St',
       secondLine: 'Unit #2',
@@ -107,29 +117,69 @@ The WForm component language can be set to 'en', 'fr', or 'es'.
 
 See the `Locale` type below.
 
+## useTaxbit Hook
+
+The `useTaxbit` hook can be used to get the data from the server or the account status.
+
+```typescript
+const {
+  statusData,
+  serverData,
+  canGetDocumentUrl,
+  getNewDocumentUrl,
+  isGettingDocumentUrl,
+  documentUrl,
+} = useTaxbit(bearerToken, questionnaire);
+```
+
+It can also be used to get the document URL for the user's tax documentation. The `getNewDocumentUrl` function will trigger a temporary URL generation. The `documentUrl` will be the URL of the document if it is available. `isGettingDocumentUrl` will be true while the URL is being generated. `canGetDocumentUrl` will be true if the user has submitted the questionnaire and a PDF tax document is available to this user. Note, `DPS` data does not generate a PDF document.
+
+### Server Data
+
+The serverData object contains the currently saved tax documentation data for the user. It is also a `ClientTaxDocumentation` object.
+
 ### Status
 
 The `useTaxbit` hook will return a `status` object that can be used to determine the status of the user's tax documentation. The `status` object will have the following shape:
 
 ```typescript
-{
-  submissionStatus: 'SUBMITTED' | 'NOT_SUBMITTED';
-  dpsQuestionnaire: {
+type ClientTaxDocumentationStatus = {
+  dpsQuestionnaire?: {
     dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
-    expirationDate: 'PENDING' |
-      'VALID' |
-      'INVALID' |
-      'INSUFFICIENT_DATA' |
-      'NOT_REQUIRED';
-  }
-}
+    vatStatus?:
+      | 'PENDING'
+      | 'VALID'
+      | 'INVALID'
+      | 'INSUFFICIENT_DATA'
+      | 'NOT_REQUIRED'
+      | 'NON_EU';
+    vatValidationDate?: string;
+    expirationDate?: string;
+  };
+  wFormQuestionnaire?: {
+    dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
+    type: 'W-9' | 'W-8BEN' | 'W-8BEN-E';
+    expirationDate?: string;
+    tinStatus?:
+      | 'PENDING'
+      | 'FOREIGN'
+      | 'INVALID_DATA'
+      | 'VALID_SSN_MATCH'
+      | 'VALID_EIN_MATCH'
+      | 'VALID_SSN_EIN_MATCH'
+      | 'MISMATCH'
+      | 'TIN_NOT_ISSUED'
+      | 'ERROR';
+    tinValidationDate?: string;
+    needsResubmission: boolean;
+  };
+};
 ```
 
 an example is below.
 
 ```json
 {
-  "submissionStatus": "SUBMITTED",
   "dpsQuestionnaire": {
     "dataCollectionStatus": "COMPLETE",
     "expirationDate": "2026-11-20T00:00:00.000Z"
@@ -137,6 +187,19 @@ an example is below.
 }
 ```
 
+or for W-Form status
+
+```json
+{
+  "wFormQuestionnaire": {
+    "dataCollectionStatus": "COMPLETE",
+    "type": "W-9",
+    "tinValidationDate": "2027-11-01T17:09:05.962Z",
+    "needsResubmission": false
+  }
+}
+```
+
 ### CSS and Style Customization
 
 The Taxbit React SDK renders a form for collecting user data. The form is structured with fairly semantic HTML and CSS classes and can be easily customized to closely match your client's style.
@@ -221,8 +284,25 @@ type Progress = {
 };
 ```
 
+```typescript
+type QuestionnaireType = 'DPS' | 'W-FORM';
+```
+
 ## Changelog
 
+### Version 1.0.0-beta.4
+
+1. More explicit typing for TaxbitQuestionnaire component props
+
+### Version 1.0.0-beta.3
+
+1. Transforming deprecated tax documentation data types for import to SDK
+2. More Readme documentation around Status and Questionnaire types
+
+### Version 1.0.0-beta.2
+
+1. The ClientTaxDocumentation type is exposed in the `useTaxbit` hook.
+
 ### Version 1.0.0-beta.1
 
 1. Showing "\*" when required for Addresses on Summary
@@ -271,7 +351,7 @@ type Progress = {
 
 ### Version 0.4.1
 
-1. Bug fix for onProgress callback not being triggered from the TaxbitDPSQuestionnaire component.
+1. Bug fix for onProgress callback not being triggered from the TaxBitDAC7Form component.
 
 ### Version 0.4.0
 
@@ -304,5 +384,5 @@ type Progress = {
 1. Fix in package.json to expose UMD module as main.
 2. Added specific CSS class names for each question and each screen of the form.
 3. Added the new status structure into the useTaxbit hook.
-4. TaxbitDPSQuestionnaire component will now preload the form with previously submitted data.
+4. TaxBitDAC7Form component will now preload the form with previously submitted data.
 5. Validation update to enforce that primary address country and tax residence country are the same.

package/dist/src/contexts/TaxDocumentation/useTaxDocumentation.d.ts

@@ -10,7 +10,7 @@ export type UseTaxDocumentationProps = {
     data?: ClientTaxDocumentation;
     language?: Locale;
     externalValidations?: ExternalValidations;
-    onSubmit: (data: ClientTaxDocumentation) => void | Promise<void>;
+    onSubmit?: (data?: ClientTaxDocumentation) => void | Promise<void>;
     onProgress?: (progress: Progress) => void | Promise<void>;
     step?: InputStep;
     questionnaire: Questionnaire;

package/dist/src/entry/TaxbitQuestionnaire/TaxbitQuestionnaire.d.ts

@@ -1,12 +1,26 @@
+import { ClientTaxDocumentation } from '@taxbit/utilities';
 import React from 'react';
-import { TaxbitQuestionnairePersistProps } from 'widgets';
-import { TaxbitQuestionnaireUIProps } from 'wizard';
-import { Questionnaire } from '../../types';
+import type { Locale, Questionnaire } from '../../types';
+import { TaxbitQuestionnairePersistProps } from '../../widgets';
 export type TaxbitQuestionnaireProps = {
+    data?: ClientTaxDocumentation;
+    language?: Locale;
     questionnaire: Questionnaire;
-} & ((TaxbitQuestionnaireUIProps & {
+    onProgress?: TaxbitQuestionnairePersistProps['onProgress'];
+    onSubmit?: TaxbitQuestionnairePersistProps['onSubmit'];
+} & ({
     demoMode: true;
-}) | (TaxbitQuestionnairePersistProps & {
+    bearerToken?: never;
+    onSuccess?: never;
+    onSettled?: never;
+    onError?: never;
+    staging?: never;
+} | {
     demoMode?: false | undefined;
-}));
-export declare const TaxbitQuestionnaire: ({ ...props }: TaxbitQuestionnaireProps) => React.JSX.Element;
+    bearerToken: TaxbitQuestionnairePersistProps['bearerToken'];
+    onSuccess?: TaxbitQuestionnairePersistProps['onSuccess'];
+    onSettled?: TaxbitQuestionnairePersistProps['onSettled'];
+    onError?: TaxbitQuestionnairePersistProps['onError'];
+    staging?: TaxbitQuestionnairePersistProps['staging'];
+});
+export declare const TaxbitQuestionnaire: ({ questionnaire, data, onSubmit, onSuccess, onSettled, onError, language, onProgress, bearerToken, demoMode, staging, }: TaxbitQuestionnaireProps) => React.JSX.Element;

package/dist/src/hooks/useTaxbit/types/comprehensive.d.ts

@@ -0,0 +1,6 @@
+import { SignedDatedComprehensiveTaxDocumentation } from '@taxbit/utilities';
+export type Comprehensive = {
+    account_holder: SignedDatedComprehensiveTaxDocumentation['account_holder'];
+    regarded_owner?: SignedDatedComprehensiveTaxDocumentation['regarded_owner'];
+    document_type: 'COMPREHENSIVE';
+};

package/dist/src/hooks/useTaxbit/types/w8.d.ts

@@ -0,0 +1,29 @@
+import { Comprehensive } from './comprehensive';
+import { W9 } from './w9';
+export type W8 = {
+    name?: string;
+    country?: string;
+    tax_classification?: 'INDIVIDUAL' | 'CORPORATION' | 'PARTNERSHIP' | 'SIMPLE_TRUST' | 'COMPLEX_TRUST' | 'GRANTOR_TRUST' | 'ESTATE' | 'CENTRAL_BANK_OF_ISSUE' | 'FOREIGN_GOVERNMENT_CONTROLLED_ENTITY' | 'FOREIGN_GOVERNMENT_INTEGRAL_PART' | 'TAX_EXEMPT_ORGANIZATION' | 'PRIVATE_FOUNDATION' | 'INTERNATIONAL_ORGANIZATION';
+    permanent_address: {
+        first_line?: string;
+        city?: string;
+        state_or_province?: string;
+        postal_code?: string;
+        country?: string;
+    };
+    mailing_address?: {
+        first_line?: string;
+        city?: string;
+        state_or_province?: string;
+        postal_code?: string;
+        country?: string;
+    };
+    reference_numbers?: string;
+    tin?: string;
+    ftin?: string;
+    date_of_birth?: string;
+    ftin_not_legally_required?: true;
+    document_type: 'W-8BEN' | 'W-8BEN-E';
+};
+export declare const isW8TaxDocument: (taxDocument: Comprehensive | W9 | W8) => taxDocument is W8;
+export declare const transformW8ToComprehensive: (taxDocument: W8) => Comprehensive;

package/dist/src/hooks/useTaxbit/types/w9.d.ts

@@ -0,0 +1,22 @@
+import { Comprehensive } from './comprehensive';
+import { W8 } from './w8';
+export type W9 = {
+    name?: string;
+    tin?: string;
+    dba_name?: string;
+    tax_classification?: 'INDIVIDUAL' | 'LLC_S' | 'LLC_C' | 'LLC_P' | 'S_CORPORATION' | 'C_CORPORATION' | 'PARTNERSHIP' | 'TRUST_ESTATE' | 'OTHER';
+    address: {
+        first_line?: string;
+        second_line?: string;
+        city?: string;
+        state_or_province?: string;
+        postal_code?: string;
+        country?: string;
+    };
+    document_type: 'W-9';
+    other_tax_classification?: string;
+    exempt_payee_code?: string;
+    exempt_fatca_code?: string;
+};
+export declare const isW9TaxDocument: (taxDocument: Comprehensive | W9 | W8) => taxDocument is W9;
+export declare const transformW9ToComprehensive: (taxDocument: W9) => Comprehensive;

package/dist/src/hooks/useTaxbit/useTaxbitConnect.d.ts

@@ -1,7 +1,7 @@
 import type { SignedClientTaxDocumentation } from '@taxbit/utilities';
 import { Questionnaire } from 'types';
 export declare const useTaxbitConnect: (bearerToken: string, questionnaire: Questionnaire, staging?: boolean) => {
-    doPostData: (data: SignedClientTaxDocumentation) => Promise<Response>;
+    doPostData: (data?: SignedClientTaxDocumentation) => Promise<Response>;
     formStatus: "COMPLETE" | "INCOMPLETE" | undefined;
     serverData: SignedClientTaxDocumentation | undefined;
     statusData: import("../../entry").ClientTaxDocumentationStatus | undefined;

package/dist/src/hooks/useTaxbit/useTaxbitStatus.d.ts

@@ -1,6 +1,6 @@
 import type { SignedClientTaxDocumentation } from '@taxbit/utilities';
-import { Questionnaire } from 'types';
-import type { ClientTaxDocumentationStatus } from 'types/client';
+import { Questionnaire } from '../../types';
+import type { ClientTaxDocumentationStatus } from '../../types/client';
 export declare const useTaxbitStatus: (bearerToken: string, questionnaire: Questionnaire, staging?: boolean) => {
     formStatus: "COMPLETE" | "INCOMPLETE" | undefined;
     serverData: SignedClientTaxDocumentation | undefined;

package/dist/src/types/client/ClientTaxDocumentationStatus.d.ts

@@ -1,9 +1,7 @@
 export type ClientTaxDocumentationStatus = {
-    status: 'UNDOCUMENTED' | 'UNDETERMINED';
-    submissionStatus: 'SUBMITTED' | 'NOT_SUBMITTED';
     dpsQuestionnaire?: {
         dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
-        vatStatus?: 'PENDING' | 'VALID' | 'INVALID' | 'INSUFFICIENT_DATA' | 'NOT_REQUIRED';
+        vatStatus?: 'PENDING' | 'VALID' | 'INVALID' | 'INSUFFICIENT_DATA' | 'NOT_REQUIRED' | 'NON_EU';
         vatValidationDate?: string;
         expirationDate?: string;
     };
@@ -11,7 +9,7 @@ export type ClientTaxDocumentationStatus = {
         dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
         type: 'W-9' | 'W-8BEN' | 'W-8BEN-E';
         expirationDate?: string;
-        tinStatus?: string;
+        tinStatus?: 'PENDING' | 'FOREIGN' | 'INVALID_DATA' | 'VALID_SSN_MATCH' | 'VALID_EIN_MATCH' | 'VALID_SSN_EIN_MATCH' | 'MISMATCH' | 'TIN_NOT_ISSUED' | 'ERROR';
         tinValidationDate?: string;
         needsResubmission: boolean;
     };

package/dist/src/types/server/TaxDocumentationStatus.d.ts

@@ -1,9 +1,7 @@
 export type TaxDocumentationStatus = {
-    status: 'UNDOCUMENTED' | 'UNDETERMINED';
-    submission_status: 'SUBMITTED' | 'NOT_SUBMITTED';
     dps_questionnaire?: {
         data_collection_status: 'COMPLETE' | 'INCOMPLETE';
-        vat_status?: 'PENDING' | 'VALID' | 'INVALID' | 'INSUFFICIENT_DATA' | 'NOT_REQUIRED';
+        vat_status?: 'PENDING' | 'VALID' | 'INVALID' | 'INSUFFICIENT_DATA' | 'NOT_REQUIRED' | 'NON_EU';
         vat_validation_date?: string;
         expiration_date?: string;
     };
@@ -11,7 +9,7 @@ export type TaxDocumentationStatus = {
         data_collection_status: 'COMPLETE' | 'INCOMPLETE';
         type: 'W-9' | 'W-8BEN' | 'W-8BEN-E';
         expiration_date?: string;
-        tin_status?: string;
+        tin_status?: 'PENDING' | 'FOREIGN' | 'INVALID_DATA' | 'VALID_SSN_MATCH' | 'VALID_EIN_MATCH' | 'VALID_SSN_EIN_MATCH' | 'MISMATCH' | 'TIN_NOT_ISSUED' | 'ERROR';
         tin_validation_date?: string;
         needs_resubmission: boolean;
     };

package/dist/src/widgets/TaxbitQuestionnairePersist/TaxbitQuestionnairePersist.d.ts

@@ -1,5 +1,5 @@
-import type { UseTaxDocumentationProps } from 'contexts';
 import React from 'react';
+import type { UseTaxDocumentationProps } from '../../contexts';
 import { UseTaxbitPersistProps } from './useTaxbitPersist';
-export type TaxbitQuestionnairePersistProps = Omit<UseTaxDocumentationProps, 'onSubmit'> & UseTaxbitPersistProps;
+export type TaxbitQuestionnairePersistProps = UseTaxDocumentationProps & UseTaxbitPersistProps;
 export declare const TaxbitQuestionnairePersist: ({ staging, data, bearerToken, language, questionnaire, onProgress, onSubmit, onSettled, onSuccess, onError, }: TaxbitQuestionnairePersistProps) => React.JSX.Element;

package/dist/src/widgets/TaxbitQuestionnairePersist/useTaxbitPersist.d.ts

@@ -1,7 +1,7 @@
-import { ClientTaxDocumentation, SignedClientTaxDocumentation } from '@taxbit/utilities';
+import { ClientTaxDocumentation } from '@taxbit/utilities';
 import { Questionnaire } from 'types';
 import { ExternalValidations } from 'types/client';
-type TaxbitResponseError = {
+export type TaxbitResponseError = {
     message: string;
     response: Response;
 };
@@ -16,10 +16,9 @@ export type UseTaxbitPersistProps = {
     onSubmit?: (data?: ClientTaxDocumentation) => void | Promise<void>;
 };
 export declare const useTaxbitPersist: ({ bearerToken, data, onSubmit, onSuccess, onSettled, onError, staging, questionnaire, }: UseTaxbitPersistProps) => {
-    handleOnSubmit: (data: SignedClientTaxDocumentation) => Promise<void>;
+    handleOnSubmit: (data?: ClientTaxDocumentation) => Promise<void>;
     externalValidations: ExternalValidations;
     formData: ClientTaxDocumentation;
     isComplete: boolean;
     isLoading: boolean;
 };
-export {};