[ai-form-recognizer] Merge 4.0.0-beta3 to main (#20236)

* [ai-form-recognizer] Support 2022-01-30-preview

* Updated tests, added language, and re-recorded

* Fixed lint errors

* Added support for prebuilt-read and prebuilt-tax.us.w2

* Update samples

* Update API review

* Remove all recordings

* Update CHANGELOG

* Update API

* Updated tests for API changes, added  and used it for the W2 tests

* Recorded tests

* Remove bad import paths

* Addressed some feedback items

* Fixed schema for w2

* Fixed a schema error

* Recorded AAD tests

* Addressed Krista's feedback.

* Updated representation of `tags`

* CapitalLetter -> EnglishCapitalLetter

* Un-updated FormRecognizerRequestBody

* Added document field exhaustiveness check

* Fix no-case-declaration lints

* Update shrinkwrap

* Updated receipt by ID sample to match receipt prebuilt

sdk/formrecognizer/ai-form-recognizer/CHANGELOG.md

@@ -1,13 +1,36 @@
 # Release History
 
-## 4.0.0-beta.3 (Unreleased)
+## 4.0.0-beta.3 (2022-02-10)
 
 ### Features Added
 
+- Updated the SDK to use the latest preview version of the Form Recognizer service: `2022-01-30-preview`.
+- A new prebuilt model, `PrebuiltModels.TaxUsW2`, is available. It supports extracting data from United States W2 tax forms such as employee and employer information, IRS control number, tax withholding information, etc.
+- Added a new method, `beginReadDocument` to `DocumentAnalysisClient`. This method uses the "prebuilt-read" model to extract textual information from the document such as page text contents and language spans.
+- Added a `languages` field to the `AnalyzeResult` type. This field contains information about regions of text in the document that were identified as being of a particular written language. A `DocumentLanguage` consists of the identified `languageCode` (ISO 639-1 or BCP 47 language code), a list of `spans` of text that are of that language, and a `confidence` value (between zero and one) that the assessment is correct.
+- Added a `tags` field to `BuildModelOptions`, `GetCopyAuthorizationOptions`, and `ModelSummary`. Tags are user-specified key-value pairs that are immutably associated with the model. If tags are provided when a model is created, the Form Recognizer service will return the same tags as part of the model's summary. The `OperationInfo` and `TrainingPollOperationState` of a model creation operation also produce the `tags` if they were provided in the `BuildModelOptions`.
+- Models now report the service API version used to create the model and that will be used for analysis in the `apiVersion` field.
+- Documents may now contain a new field type `DocumentCurrencyField`, which has an object with `amount` and `currencySymbol` fields as its value. This field is identified by the value `"currency"` in the `kind` field. The `amount` field contains the amount of the currency value, and the `currencySymbol` field may contain a three-letter currency symbol if one was identified for the field. For example, the text `$100.50` may have an `amount` of `100.5` and a `currencySymbol` of "USD".
+- Added support for setting the `buildMode` of a model building operation and introduced the "neural" build mode. Previous versions of the service and SDK only supported a single build mode that is now known as the "template" mode. Template models only accept documents that have the same basic page structure (i.e. a uniform visual appearance, or the same _relative_ positioning of elements within the document), hence a fixed document "template." Neural models support document classes that have the same information, but different page structures. Examples of these documents include United States W2 tax forms, which all share the same information, but may vary in appearance by the company that created the document. Neural models currently only support English text, and are more costly and time-consuming to train and use for analysis, but should yield higher-quality results for English documents that do not follow a "template."
+- The `DocTypeInfo` type now has a `buildMode` field that contains the build mode originally used to create the document type.
+
 ### Breaking Changes
 
+- Renamed the `beginAnalyzeDocuments` method of `DocumentAnalysisClient` to `beginAnalyzeDocument` for accuracy (only one input document is supported, though the document may contain multiple pages in certain file formats) and for consistency with other Azure SDK packages.
+  - Renamed the options bag type `AnalyzeDocumentsOptions` to `AnalyzeDocumentOptions` for consistency with the method name.
+- The `buildMode` parameter of `DocumentModelAdminsitrationClient#beginBuildModel` is a required parameter. To retain the same behavior as in previous versions, explicitly use the template build mode (pass the value `"template"` to the method).
+- The `GeneratedDocument` type (as well as related types like `GeneratedDocumentField`) was removed from the public API and its uses replaced with `unknown`, as it is only intended for internal use. These types represented raw REST API response types that are not exposed at runtime by the client methods.
+- Removed the `Preview` variant from the `FormRecognizerApiVersion` object because it will never be different from the `Latest` version in beta packages, and stable packages will not support it.
+- Renamed `beginExtractGenericDocument` and `GenericDocumentResult` to `beginExtractGeneralDocument` and `GeneralDocumentResult` for consistency with other Form Recognizer SDK packages.
+- Several of the prebuilt model schemas and result types have changed:
+  - The document type naming convention has changed. Instead of separation by colons (e.g. "prebuilt:receipt"), prebuilt model document type names are now separated by periods and are no longer prefixed with "prebuilt" ("prebuilt:idDocument:driverLicense" becomes "idDocument.driverLicense", "prebuilt:invoice" becomes just "invoice").
+  - In the `prebuilt-invoice` model, several numeric fields that represented amounts of money have been changed to a designated `"currency"` type. These include the `subTotal`, `totalTax`, `invoiceTotal`, `amountDue`, and `previousUnpaidBalance` fields of invoices and the `amount`, `tax`, and `unitPrice` fields of invoice items (a subfield of invoices).
+
 ### Bugs Fixed
 
+- The `LayoutResult` and `GeneralDocumentResult` types were missing the `apiVersion`, `modelId`, and `content` fields that are common to all other analysis results. This version adds them through a new interface, `AnalyzeResultCommon`, that includes these fields. `LayoutResult`, `GeneralDocumentResult`, `ReadResult`, and `AnalyzeResult` all now extend the `AnalyzeResultCommon` interface.
+- The `DocumentSignatureField` interface was missing a type for its `value` property. The property existed at runtime, but no type information was available for this field. The `value` property has been added to the interface.
+
 ### Other Changes
 
 - Changed `FormRecognizerCommonClientOptions` to extend `CommonClientOptions` from `@azure/core-client` instead of `PipelineOptions`. `CommonClientOptions` itself extends `PipelineOptions`, so no fields are removed, but `CommonClientOptions` also includes `httpClient` and `allowInsecureConnection` fields to allow overriding the default HTTP client and using insecure connections (without SSL/TLS) respectively.
@@ -188,7 +211,7 @@ This new major version beta introduces a full redesign of the Azure Form Recogni
   - [Breaking] Remove `getFormTrainingClient()` from `FormRecognizerClient`. A new method `getFormRecognizerClient()` is added to `FormTrainingClient`
   - [Breaking] `useTrainingLabels` parameter is now required for `beginTraining()` method.
   - [Breaking] Rename `intervalInMs` to `updateIntervalInMs` for all LRO poller options.
-  - [Breaking] Remove `USReceipt` and assoicated types.
+  - [Breaking] Remove `USReceipt` and associated types.
   - Rename the first parameter of `beginRecognizeContent()` from `data` to `form`.
   - Rename the second parameter of `beginRecognizeForms()` from `data` to `form`.
   - Rename the first parameter of `beginRecognizeReceipts()` from `data` to `receipt`.

sdk/formrecognizer/ai-form-recognizer/package.json

@@ -86,7 +86,7 @@
     "@azure/core-paging": "^1.1.1",
     "@azure/core-rest-pipeline": "^1.1.0",
     "@azure/core-client": "^1.0.0",
-    "@azure/core-tracing": "1.0.0-preview.13",
+    "@azure/core-tracing": "1.0.0-preview.14",
     "@azure/logger": "^1.0.0",
     "tslib": "^2.2.0"
   },