opendata/readme.md

# @fin.cx/opendata

A TypeScript-based library for accessing and managing open business data, specifically for German companies.

## Install

To install the `@fin.cx/opendata` package, you can use npm or yarn as your package manager. Here's how you can do it:

Using npm:

```bash
npm install @fin.cx/opendata
```

Using yarn:

```bash
yarn add @fin.cx/opendata
```

## Usage

The `@fin.cx/opendata` package provides a comprehensive set of functionalities for handling open business data, focusing on German business data. Let's explore the detailed capabilities of this library through extensive examples and instructions.

### Setting Up the Environment

First, make sure you've set up the necessary environment variables for MongoDB. You will need the following environment variables:
- `MONGODB_URL`: The URL for your MongoDB instance.
- `MONGODB_NAME`: The name of the database to use.
- `MONGODB_USER`: A valid username for accessing the database.
- `MONGODB_PASS`: The password associated with the MongoDB user.

These variables can be configured in a `.env` file or managed through a specific service used for secure environment variables handling.

### Importing and Initializing the Library

To start working with the library, import the necessary classes and initialize the `OpenData` class.

```typescript
import { OpenData } from '@fin.cx/opendata';

const initializeOpenData = async () => {
  const openData = new OpenData();
  
  try {
    await openData.start();
    console.log('OpenData instance has started successfully.');
    
    // Example usage:
    await createAndManageBusinessRecords(openData);

  } catch (error) {
    console.error('Error starting OpenData:', error);
  } finally {
    await openData.stop();
    console.log('OpenData instance has stopped.');
  }
};

initializeOpenData();
```

### Managing Business Records

The `BusinessRecord` class represents a company's data. Let's explore how you can create, retrieve, update, and manage these records.

#### Creating a New BusinessRecord

Creating a new business record involves instantiating the `BusinessRecord` class and setting the relevant properties.

```typescript
import { BusinessRecord } from '@fin.cx/opendata';

const createBusinessRecord = async (openData: OpenData) => {
  const businessRecord = new openData.CBusinessRecord();
  
  businessRecord.data = {
    name: "Tech Innovations GmbH",
    address: "Tech Park 42",
    postalCode: "80333",
    city: "Munich",
    country: "Germany",
    phone: "+49 89 123456",
    email: "info@techinnovations.de",
    website: "https://techinnovations.de",
    businessType: "GmbH",
    registrationNumber: "HRB 654321",
    registrationCourt: "Munich",
    legalForm: "GmbH",
    managingDirectors: ["Alice Müller", "Bob Schmidt"],
    foundingDate: new Date("2020-01-01").toISOString(),
    capital: "100,000 EUR",
    purpose: "Developing innovative tech solutions",
    lastUpdate: new Date().toISOString()
  };

  await businessRecord.save();
  console.log('BusinessRecord saved:', businessRecord);
};
```

#### Retrieving Business Records

You can retrieve existing business records by querying the database using various data fields.

```typescript
const retrieveBusinessRecords = async (openData: OpenData) => {
  const records = await openData.db
    .collection<BusinessRecord>('businessrecords')
    .find({ city: "Munich" })
    .toArray();

  console.log('Found Business Records:', records);
};
```

#### Updating Existing Records

To update an existing `BusinessRecord`, you retrieve the record, modify its data, and save it again.

```typescript
const updateBusinessRecord = async (openData: OpenData, recordId: string) => {
  const businessRecord = await openData.CBusinessRecord.getInstance(recordId);
  if (businessRecord) {
    businessRecord.data.phone = "+49 89 987654";
    businessRecord.data.lastUpdate = new Date().toISOString();

    await businessRecord.save();
    console.log('BusinessRecord updated:', businessRecord);
  } else {
    console.log('BusinessRecord not found for id:', recordId);
  }
};
```

#### Deleting a Business Record

You can delete a business record using its unique identifier.

```typescript
const deleteBusinessRecord = async (openData: OpenData, recordId: string) => {
  const businessRecord = await openData.CBusinessRecord.getInstance(recordId);
  if (businessRecord) {
    await businessRecord.delete();
    console.log(`BusinessRecord with id ${recordId} deleted successfully.`);
  } else {
    console.log('No record found for the provided id:', recordId);
  }
};
```

### Updating German Business Data

The package includes functionalities to keep your business data up-to-date by downloading from official German open data repositories.

```typescript
const updateGermanBusinessData = async (openData: OpenData) => {
  try {
    await openData.germanBusinesses.update();
    console.log('German business data has been updated successfully.');
  } catch (error) {
    console.error('Error updating German business data:', error);
  }
};
```

This function fetches the latest open data regarding German companies, processes it, and updates your local database.

### Detailed Class Insights

#### OpenData Class

The `OpenData` class serves as the core of the library, initializing necessary components and controlling data flows:

- **db**: Represents the connection to your MongoDB database.
- **germanBusinesses**: An instance handling specific operations related to German business data updates.

```typescript
class OpenData {
  db: plugins.smartdata.SmartdataDb;
  germanBusinesses: GermanBusinessData;

  private serviceQenv = new plugins.qenv.Qenv(paths.packageDir, paths.nogitDir);

  public async start() {
    // Database initialization logic
  }

  public async stop() {
    // Cleanup logic
  }
}
```

#### GermanBusinessData Class

This class deals specifically with German company data — fetching, processing, and updating local databases consistently with official German data sources.

```typescript
class GermanBusinessData {
  public async start() {
    await this.update();
  }

  public async update() {
    // Logic for updating business data using import streams and parsing JSON lines.
  }
}
```

### Ensuring Data Accuracy and Integrity

When working with business data, ensuring integrity and accuracy is crucial. Each record should be checked for validity before being saved or updated, minimizing inconsistencies. Moreover, robust error handling is essential in every step, from data retrieval to database operations, particularly when dealing with external data sources.

The `@fin.cx/opendata` module provides an extensive toolset for accessing and managing business data, particularly for companies based in Germany. Its functionalities include creating, updating, retrieving, and deleting business records, as well as keeping them current with the latest open data releases. This makes it an invaluable asset for developers aiming to integrate open data seamlessly into their systems, ensuring robust data management capabilities within their applications.

Happy exploring and integrating open data into your projects!

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.