@ingestro/importer-vanilla-js 4.0.1

package/README.md

@@ -0,0 +1,199 @@
+<!-- markdownlint-disable -->
+<p align="center">
+  <a href="https://ingestro.com/" rel="noopener" target="_blank"><img width="150" src="https://general-upload.ingestro.com/nuvo_logo_with_text.svg" alt="nuvo logo"></a>
+</p>
+
+<h1 align="center">@getnuvo/importer-vanilla-js</h1>
+
+<div align="center">
+
+[![npm latest package](https://img.shields.io/npm/v/@getnuvo%2Fimporter-vanilla-js?color=5c8ef2&label=npm@latest)](https://badge.fury.io/js/@getnuvo%2Fimporter-vanilla-js)
+[![API status](https://img.shields.io/uptimerobot/ratio/m792354517-acd98c6100961072cc093759?color=2fa659&label=uptime)](https://status.ingestro.com/)
+
+</div>
+
+> [!NOTE]
+> The `@getnuvo/importer-vanilla-js` package is the successor to our previous `nuvo-vanilla-js` package.
+> While you can continue using versions 2.x of `nuvo-vanilla-js`, we recommend migrating to
+> `@getnuvo/importer-vanilla-js` version 3.x to take advantage of the latest features and improvements.
+
+# nuvo Data Importer Vanilla JS SDK
+
+**nuvo** leverages AI to simplify importing complex and unstructured files into your application.
+
+Integrate the nuvo Data Importer to offer your customers an intuitive and efficient data import experience.
+
+## Features
+
+- **AI-Powered Column and Option Mapping**: Automatically matches imported data columns to your system's target data model, streamlining the import process.
+- **Customizable Cleaning Functions**: Implement custom logic to validate and transform data during the import workflow.
+- **Support for Multiple File Formats**: Handles various file types, including CSV, TSV, XLS, XLSX, JSON, XML, and PDF.
+- **Dynamic Import Capabilities**: Initiate the import process from any step, accommodating diverse data sources and workflows.
+- **Styling and Theming**: Easily adjust the importer's appearance to align with your application's design.
+- **Multi-language Support**: Customize and localize interface text to cater to a global user base.
+
+## Getting Started
+
+Ensure you have signed up on our [User Platform](https://dashboard.ingestro.com/) and have access to your nuvo license key.
+
+### Installation
+
+Add nuvo to your project:
+
+**npm:**
+
+```bash
+npm install @getnuvo/importer-vanilla-js
+```
+
+**yarn:**
+
+```bash
+yarn add @getnuvo/importer-vanilla-js
+```
+
+### Basic Implementation
+
+Below is a basic example of integrating the `NuvoImporter` component into your Vanilla JS application:
+
+CDN:
+
+```js
+<div class="nuvo-container" />
+<script type="module">
+  import { launchDataImporter } from 'https://unpkg.com/@getnuvo/importer-vanilla-js';
+
+  launchDataImporter('.nuvo-container', {
+    licenseKey: 'Your License Key',
+    settings: {
+      identifier: 'product_data',
+      columns: [
+          {
+            label: 'Product ID',
+            key: 'product_id',
+          },
+          {
+            label: 'Article Name',
+            key: 'article_name',
+          },
+        ],
+    },
+    onResults: (results, errors, complete, logs) => {
+      console.log('Imported Data:', results);
+      console.log('Errors:', errors);
+      console.log('Import Logs:', logs);
+      complete(); // Finalize the import process
+    },
+  });
+</script>
+```
+
+NPM:
+
+```js
+<div class="nuvo-container" />
+<script type="module">
+  import { launchDataImporter } from '@getnuvo/importer-vanilla-js';
+
+  launchDataImporter('.nuvo-container', {
+    licenseKey: 'Your License Key',
+    settings: {
+      identifier: 'product_data',
+      columns: [
+          {
+            label: 'Product ID',
+            key: 'product_id',
+          },
+          {
+            label: 'Article Name',
+            key: 'article_name',
+          },
+        ],
+    },
+    onResults: (results, errors, complete, logs) => {
+      console.log('Imported Data:', results);
+      console.log('Errors:', errors);
+      console.log('Import Logs:', logs);
+      complete(); // Finalize the import process
+    },
+  });
+</script>
+```
+
+In this example:
+
+- **licenseKey**: Your unique nuvo license key.
+- **settings**: Configuration object for the importer.
+- **identifier**: A unique string to identify the import instance.
+- **columns**: Defines the target data model (TDM) with `label` and `key` for each column.
+- **onResults**: Callback function that handles the imported data results.
+
+For a comprehensive guide on setting up and customizing the importer, refer to the [First Steps](https://docs.ingestro.com/sdk/start/) documentation.
+
+## Advanced Configuration
+
+### Settings & Configuration
+
+The `settings` property allows you to tailor the importer's behavior and appearance. Key configurable options include:
+
+- **inputTypes**: Specify supported file types (e.g., `['csv', 'xls', 'json']`).
+- **modal**: Determine whether the importer operates within a modal (`true`) or inline (`false`).
+
+For a detailed list of configuration options, visit the [Settings & Configuration](https://docs.ingestro.com/sdk/settings/) page.
+
+### Target Data Model (TDM)
+
+Define the structure of the data you expect using the `columns` array within the `settings`. Each column can include:
+
+- **label**: User-friendly name displayed in the UI.
+- **key**: Technical identifier for the column.
+- **description**: Additional information about the column.
+- **alternativeMatches**: Array of synonyms or abbreviations to assist the mapping algorithm.
+- **validations**: Rules such as required fields, uniqueness, regex patterns, and cross-column dependencies.
+
+Learn more about defining your TDM in the [Columns / Target Data Model](https://docs.ingestro.com/sdk/columns/) documentation.
+
+### Cleaning & Data Handler Functions
+
+Implement custom cleaning & data handler functions (callback functions) to transform and validate data during the import process. These functions can correct date formats, enrich entries, compare imported data against external databases, and more.
+
+Explore the capabilities of these functions in the [Cleaning Functions](https://docs.ingestro.com/sdk/cleaning-functions/) & [Data Handler](https://docs.ingestro.com/sdk/data-handler) docs.
+
+### Dynamic Import
+
+The dynamic import feature allows you to start the import process from any step and with various data formats. This flexibility enables integration with different workflows and data sources.
+
+For implementation details, refer to the [Dynamic Import](https://docs.ingestro.com/sdk/dynamic-import/) documentation.
+
+### Styling and Theming
+
+Customize the appearance of the nuvo importer to match your application's design. Modify themes, adjust display modes, and enable or disable specific features to create a seamless user experience.
+
+Learn more about styling options in the [Styling](https://docs.ingestro.com/sdk/styling/) section.
+
+### Multi-language Support
+
+The `i18nOverrides` and `language` feature allow you to customize and localize the application's default language keys, ensuring the importer aligns with your users' language preferences.
+
+For more information on localization, visit the [Multi-language Support](https://docs.ingestro.com/sdk/multi-language/) & [Language](https://docs.ingestro.com/sdk/settings#language) page.
+
+## Handling Results
+
+The `onResults` callback function provides access to the cleaned data, allowing you to define how to process and store it.
+
+Detailed information on handling results can be found in the [Result (Output)](https://docs.ingestro.com/sdk/results/) documentation.
+
+## Release Notes
+
+Stay updated with the latest features, improvements, and bug fixes by reviewing our [Release Notes](https://docs.ingestro.com/sdk/release-notes/).
+
+## Learn More
+
+Explore how to get the most out of nuvo with real examples and detailed guides:
+
+- Try it live on [CodeSandbox](https://codesandbox.io/p/devbox/dank-feather-qt3n87) – test and tweak the importer in action.
+- Visit our [Knowledge Base](https://dashboard.ingestro.com/knowledge-base) for deep dives into settings, data models, cleaning functions, and more.
+
+## Support
+
+If you have any questions or need assistance, please refer to our [FAQ](https://docs.ingestro.com/sdk/faq) or contact our support team at [support@ingestro.com](mailto:support@ingestro.com).