@fin.cx/opendata 3.6.0 → 4.1.0

package/dist_ts/laws/index.d.ts

@@ -1,3 +0,0 @@
-export * from './interfaces.law.js';
-export * from './classes.lawrecord.js';
-export * from './classes.lawservice.js';

package/dist_ts/laws/index.js

@@ -1,4 +0,0 @@
-export * from './interfaces.law.js';
-export * from './classes.lawrecord.js';
-export * from './classes.lawservice.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9sYXdzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyx3QkFBd0IsQ0FBQztBQUN2QyxjQUFjLHlCQUF5QixDQUFDIn0=

package/dist_ts/laws/interfaces.law.d.ts

@@ -1,35 +0,0 @@
-export type TJurisdiction = 'de' | 'eu' | 'us';
-export type TLawSource = 'gesetze-im-internet' | 'eur-lex' | 'law-cornell-lii' | 'govinfo-plaw' | 'govinfo-uscode';
-export type TRawLawFormat = 'xml' | 'html' | 'text' | 'json';
-export type TUsLawCollection = 'PLAW' | 'USCODE';
-export interface ILawServiceConfig {
-    dbFolderPath?: string;
-    dbName?: string;
-    govInfoApiKey?: string;
-}
-export interface ILawLookupRequest {
-    jurisdiction: TJurisdiction;
-    identifier: string;
-    language?: string;
-    usCollection?: TUsLawCollection;
-    forceSync?: boolean;
-}
-export interface ILawSyncRequest {
-    jurisdiction: TJurisdiction;
-    limit?: number;
-    offset?: number;
-    language?: string;
-    govInfoApiKey?: string;
-    usCollection?: TUsLawCollection;
-    since?: Date;
-}
-export interface ILawSearchRequest {
-    query: string;
-    jurisdiction?: TJurisdiction;
-    limit?: number;
-}
-export interface ILawSyncResult {
-    jurisdiction: TJurisdiction;
-    syncedCount: number;
-    identifiers: string[];
-}

package/dist_ts/laws/interfaces.law.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5sYXcuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9sYXdzL2ludGVyZmFjZXMubGF3LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIifQ==

package/readme.hints.md

@@ -1,89 +0,0 @@
-# OpenData Project Hints
-
-## Stocks Module
-
-### Overview
-The stocks module provides real-time stock price data and cryptocurrency prices through various provider implementations. Currently supports Yahoo Finance, Marketstack, and CoinGecko with an extensible architecture for additional providers.
-
-### Architecture
-- **Provider Pattern**: Each stock data source implements the `IStockProvider` interface
-- **Service Registry**: `StockPriceService` manages providers with priority-based selection
-- **Caching**: Built-in cache with configurable TTL to reduce API calls
-- **Fallback Logic**: Automatic failover between providers if one fails
-
-### Yahoo Finance Provider Notes
-- Uses public API endpoints (no authentication required)
-- Two main endpoints:
-  - `/v8/finance/chart/{ticker}` - Single ticker with full data
-  - `/v8/finance/spark?symbols={tickers}` - Multiple tickers with basic data
-- Response data is in `response.body` when using smartrequest
-- Requires User-Agent header to avoid rate limiting
-
-### Usage Example
-```typescript
-import { StockPriceService, YahooFinanceProvider } from '@fin.cx/opendata';
-
-const stockService = new StockPriceService({ ttl: 60000 });
-const yahooProvider = new YahooFinanceProvider();
-stockService.register(yahooProvider);
-
-const price = await stockService.getPrice({ ticker: 'AAPL' });
-console.log(`${price.ticker}: $${price.price}`);
-```
-
-### CoinGecko Provider Notes
-- Cryptocurrency price provider supporting 13M+ tokens
-- Three main endpoints:
-  - `/simple/price` - Current prices with market data (batch supported)
-  - `/coins/{id}/market_chart` - Historical and intraday prices with OHLCV
-  - `/coins/list` - Complete coin list for ticker-to-ID mapping
-- **Rate Limiting**:
-  - Free tier: 5-15 calls/minute (no registration)
-  - Demo plan: 30 calls/minute, 10,000/month (free with registration)
-  - Custom rate limiter tracks requests per minute
-- **Ticker Resolution**:
-  - Accepts both ticker symbols (BTC, ETH) and CoinGecko IDs (bitcoin, ethereum)
-  - Lazy-loads coin list on first ticker resolution
-  - Caches coin mappings for 24 hours
-  - IDs with hyphens (wrapped-bitcoin) assumed to be CoinGecko IDs
-- **24/7 Markets**: Crypto markets always return `marketState: 'REGULAR'`
-- **Optional API Key**: Pass key to constructor for higher rate limits
-  - Demo plan: `x-cg-demo-api-key` header
-  - Paid plans: `x-cg-pro-api-key` header
-- **Data Granularity**:
-  - Historical: Daily data for date ranges
-  - Intraday: Hourly data only (1-90 days based on `days` param)
-  - Current: Real-time prices with 24h change and volume
-
-### Usage Example (Crypto)
-```typescript
-import { StockPriceService, CoinGeckoProvider } from '@fin.cx/opendata';
-
-const stockService = new StockPriceService({ ttl: 30000 });
-const coingeckoProvider = new CoinGeckoProvider(); // or new CoinGeckoProvider('api-key')
-stockService.register(coingeckoProvider);
-
-// Using ticker symbol
-const btc = await stockService.getPrice({ ticker: 'BTC' });
-console.log(`${btc.ticker}: $${btc.price}`);
-
-// Using CoinGecko ID
-const ethereum = await stockService.getPrice({ ticker: 'ethereum' });
-
-// Batch fetch
-const cryptos = await stockService.getPrices({ tickers: ['BTC', 'ETH', 'USDT'] });
-```
-
-### Testing
-- Tests use real API calls (be mindful of rate limits)
-- Mock invalid ticker 'INVALID_TICKER_XYZ' for error testing
-- Clear cache between tests to ensure fresh data
-- The spark endpoint may return fewer results than requested
-- CoinGecko tests may take longer due to rate limiting (wait between requests)
-
-### Future Providers
-To add a new provider:
-1. Create `ts/stocks/providers/provider.{name}.ts`
-2. Implement the `IStockProvider` interface
-3. Register with `StockPriceService`
-4. No changes needed to existing code

package/ts/classes.businessrecord.ts

@@ -1,67 +0,0 @@
-import * as plugins from './plugins.js';
-
-@plugins.smartdata.Manager()
-export class BusinessRecord extends plugins.smartdata.SmartDataDbDoc<
-  BusinessRecord,
-  BusinessRecord
-> {
-  // STATIC
-  public static getByGermanParsedRegistration = async (parsedGermanRegistrationArg: BusinessRecord['data']['germanParsedRegistration']) => {
-    const businessRecords = await BusinessRecord.getInstance({
-      data: {
-        germanParsedRegistration: parsedGermanRegistrationArg,
-      }
-    });
-    return businessRecords;
-  };
-
-
-  // INSTANCE
-  @plugins.smartdata.unI()
-  id!: string;
-
-  @plugins.smartdata.svDb()
-  data: {
-    name?: string;
-    startDate?: string;
-    endDate?: string;
-    status?: 'active' | 'liquidating' | 'closed';
-    address?: string;
-    postalCode?: string;
-    city?: string;
-    country?: string;
-    phone?: string;
-    fax?: string;
-    email?: string;
-    website?: string;
-    businessType?: string;
-    registrationId?: string;
-    germanParsedRegistration?: {
-      court?: string;
-      type?: 'HRA' | 'HRB' | 'GnR' | 'PR' | 'VR' | 'GsR';
-      number?: string;
-    };
-    legalForm?:
-      | 'GmbH'
-      | 'GmbH & Co. KG'
-      | 'AG'
-      | 'LLC'
-      | 'LLP'
-      | 'GmbH & Co. KGaA'
-      | 'GmbH & Co. KGaA, LLC';
-    managingDirectors?: string[];
-    boardOfDirectors?: string[];
-    supervisoryBoard?: string[];
-    foundingDate?: string;
-    capital?: string;
-    purpose?: string;
-    lastUpdate?: string;
-  } = {};
-
-  /**
-   * validates the record against the Handelregister.
-   */
-  public async validate() {
-    if (!this.data.name) throw new Error('Name is required.');
-  }
-}

package/ts/classes.handelsregister.ts

@@ -1,385 +0,0 @@
-import type { BusinessRecord } from './classes.businessrecord.js';
-import type { OpenData } from './classes.main.opendata.js';
-import * as plugins from './plugins.js';
-
-/**
- * the HandlesRegister exposed as a class
- */
-export class HandelsRegister {
-  private openDataRef: OpenData;
-  private asyncExecutionStack = new plugins.lik.AsyncExecutionStack();
-  private downloadDir: string;
-  private uniqueDowloadFolder: string;
-
-  // Puppeteer wrapper instance
-  public smartbrowserInstance = new plugins.smartbrowser.SmartBrowser();
-
-  constructor(openDataRef: OpenData, downloadDirArg: string) {
-    this.openDataRef = openDataRef;
-    this.downloadDir = downloadDirArg;
-    this.uniqueDowloadFolder = plugins.path.join(this.downloadDir, plugins.smartunique.uniSimple());
-  }
-
-  private async resetDownloadFolder() {
-    await plugins.smartfs.directory(this.uniqueDowloadFolder).recursive().delete().catch(() => {});
-    await plugins.smartfs.directory(this.uniqueDowloadFolder).create();
-  }
-
-  private async waitForDownloadedFile() {
-    for (let attempt = 0; attempt < 120; attempt++) {
-      const directoryEntries = await plugins.fs.readdir(this.uniqueDowloadFolder);
-      const fileName = directoryEntries.find(
-        (entry) => !entry.endsWith('.crdownload') && !entry.endsWith('.tmp')
-      );
-
-      if (fileName) {
-        const filePath = plugins.path.join(this.uniqueDowloadFolder, fileName);
-        const firstStat = await plugins.fs.stat(filePath);
-        await plugins.smartdelay.delayFor(500);
-        const secondStat = await plugins.fs.stat(filePath);
-
-        if (firstStat.size === secondStat.size) {
-          return filePath;
-        }
-      }
-
-      await plugins.smartdelay.delayFor(500);
-    }
-
-    throw new Error('Timed out while waiting for the download to finish.');
-  }
-
-  public async start() {
-    // Start the browser
-    await this.resetDownloadFolder();
-    await this.smartbrowserInstance.start();
-  }
-
-  public async stop() {
-    // Stop the browser
-    await plugins.smartfs.directory(this.uniqueDowloadFolder).recursive().delete();
-    await this.smartbrowserInstance.stop();
-  }
-
-  /**
-   * Creates a new page and configures it to allow file downloads
-   * to a predefined path.
-   */
-  public getNewPage = async () => {
-    const page = await this.smartbrowserInstance.headlessBrowser.newPage();
-
-    // 1) Create a DevTools session for this page
-    const cdpSession = await page.target().createCDPSession();
-
-    // 2) Allow file downloads and set the download path
-    await cdpSession.send('Page.setDownloadBehavior', {
-      behavior: 'allow',
-      downloadPath: this.uniqueDowloadFolder, // <-- Change this to your desired absolute path
-    });
-
-    // Optionally set viewport and go to page
-    await page.setViewport({ width: 1920, height: 1080 });
-    await page.goto('https://www.handelsregister.de/');
-    return page;
-  };
-
-  private navigateToPage = async (
-    pageArg: plugins.smartbrowser.smartpuppeteer.puppeteer.Page,
-    pageNameArg: string
-  ) => {
-    try {
-      await pageArg.evaluate((pageNameArg2) => {
-        const elements = Array.from(document.querySelectorAll('.ui-menuitem-text > span'));
-        const targetElement = elements.find((el) => el.textContent?.trim() === pageNameArg2);
-        if (targetElement) {
-          (targetElement as HTMLElement).click();
-        }
-      }, pageNameArg);
-      console.log(`Navigated to the ${pageNameArg} page successfully.`);
-    } catch (error) {
-      console.error(`Failed to navigate to the ${pageNameArg} page:`, error);
-    }
-  };
-
-  private waitForResults = async (pageArg: plugins.smartbrowser.smartpuppeteer.puppeteer.Page) => {
-    await pageArg
-      .waitForSelector('#ergebnissForm\\:selectedSuchErgebnisFormTable_data', {
-        timeout: 30000,
-      })
-      .catch(async (err) => {
-        await pageArg.screenshot({ path: `${this.downloadDir}/error.png` as `${string}.png` });
-        throw err;
-      });
-
-    const businessRecords: BusinessRecord['data'][] = await pageArg.evaluate(() => {
-      const rows = document.querySelectorAll(
-        '#ergebnissForm\\:selectedSuchErgebnisFormTable_data > tr'
-      );
-      const records: BusinessRecord['data'][] = [];
-
-      rows.forEach((row) => {
-        const nameElement = row.querySelector('td.ui-panelgrid-cell span.marginLeft20');
-        const cityElement = row.querySelector('td.ui-panelgrid-cell.sitzSuchErgebnisse span');
-        const statusElement = row.querySelector('td.ui-panelgrid-cell span.verticalText');
-        const registrationCourtElement = row.querySelector(
-          'td.ui-panelgrid-cell.fontTableNameSize'
-        );
-
-        const name = nameElement?.textContent?.trim();
-        const city = cityElement?.textContent?.trim();
-        const status = statusElement?.textContent?.trim();
-        const registrationId = registrationCourtElement?.textContent?.trim();
-
-        // Push parsed data into records array
-        records.push({
-          name,
-          city,
-          registrationId,
-          businessType: status,
-        });
-      });
-
-      return records;
-    });
-    return businessRecords;
-  };
-
-  private clickFindButton = async (pageArg: plugins.smartbrowser.smartpuppeteer.puppeteer.Page, resultsLimitArg: number = 100) => {
-    try {
-      // Wait for the button with the text "Find" to appear
-      await pageArg.waitForSelector('span.ui-button-text.ui-c', { timeout: 5000 });
-
-      // adjust to 100 results per page
-      await pageArg.select('#form\\:ergebnisseProSeite_input', `${resultsLimitArg}`);
-
-      // Locate and click the button using its text
-      await pageArg.evaluate(() => {
-        const buttons = Array.from(document.querySelectorAll('span.ui-button-text.ui-c'));
-        const targetButton = buttons.find((button) => button.textContent?.trim() === 'Find');
-        if (targetButton) {
-          const parentButton = targetButton.closest('button') || targetButton;
-          (parentButton as HTMLElement).click();
-        }
-      });
-
-      console.log('Find button clicked successfully!');
-    } catch (error) {
-      console.error('Failed to find or click the "Find" button:', error);
-    }
-  };
-
-  private async downloadFile(
-    pageArg: plugins.smartbrowser.smartpuppeteer.puppeteer.Page,
-    typeArg: 'SI' | 'AD'
-  ) {
-    // Trigger the file download by clicking on the relevant link
-    await pageArg.evaluate((typeArg2) => {
-      // Locate the table body
-      const tableBody = document.querySelector(
-        '#ergebnissForm\\:selectedSuchErgebnisFormTable_data'
-      );
-      if (!tableBody) {
-        throw new Error('Table body not found');
-      }
-
-      // Locate the first row
-      const firstRow = tableBody.querySelector('tr:nth-child(1)');
-      if (!firstRow) {
-        throw new Error('First row not found');
-      }
-
-      // Locate the last cell in the first row
-      const lastCell = firstRow.querySelector('td:last-child');
-      if (!lastCell) {
-        throw new Error('Last cell not found in the first row');
-      }
-
-      // Locate the download links
-      const adLink = lastCell.querySelector('a:first-of-type');
-      const siLink = lastCell.querySelector('a:last-of-type');
-      if (!siLink) {
-        throw new Error('SI link not found in the last cell');
-      }
-
-      // Simulate a click on the last <a> element
-      switch (typeArg2) {
-        case 'AD':
-          (adLink as HTMLElement).click();
-          break;
-        case 'SI':
-          (siLink as HTMLElement).click();
-          break;
-        default:
-          throw new Error('Invalid file type');
-      }
-    }, typeArg);
-    const downloadedFilePath = await this.waitForDownloadedFile();
-    const renamedFilePath = plugins.path.join(
-      this.uniqueDowloadFolder,
-      typeArg === 'AD' ? 'ad.pdf' : 'si.xml'
-    );
-    await plugins.fs.rename(downloadedFilePath, renamedFilePath);
-    const file = await plugins.smartfileFactory.fromFilePath(renamedFilePath);
-
-    // Keep the download folder empty between requests.
-    await this.resetDownloadFolder();
-    return file;
-  }
-
-  /**
-   * Helper method to parse the German registration string
-   */
-  private async parseGermanRegistration(
-    input: string
-  ): Promise<BusinessRecord['data']['germanParsedRegistration']> {
-    // e.g. District court Berlin (Charlottenburg) HRB 123456
-    const regex =
-      /District court (\p{L}[\p{L}\s-]*?(?:\s*\([\p{L}\s-]+\))?)\s+(HRA|HRB|GnR|VR|PR|GsR)\s+(\d+)/u;
-    const match = input.match(regex);
-
-    if (match) {
-      return {
-        court: match[1],
-        type: match[2] as 'HRA' | 'HRB', // Adjust if needed
-        number: match[3],
-      };
-    }
-  }
-
-  /**
-   * Search for a company by name and return basic info
-   */
-  public async searchCompany(companyNameArg: string, resultsLimitArg: number = 100) {
-    return this.asyncExecutionStack.getExclusiveExecutionSlot(async () => {
-      const page = await this.getNewPage();
-      await this.navigateToPage(page, 'Normal search');
-
-      try {
-        // Wait for the textarea to appear
-        await page.waitForSelector('#form\\:schlagwoerter', { timeout: 5000 });
-
-        // Enter text into the textarea
-        const inputText = companyNameArg;
-        await page.evaluate((text) => {
-          const textarea = document.querySelector<HTMLTextAreaElement>('#form\\:schlagwoerter');
-          if (textarea) {
-            textarea.value = text; // Set the value
-            // Trigger the change event manually if required
-            const event = new Event('change', { bubbles: true });
-            textarea.dispatchEvent(event);
-          }
-        }, inputText);
-
-        console.log('Text entered successfully!');
-      } catch (error) {
-        console.error('Failed to find or enter text into the textarea:', error);
-      }
-
-      try {
-        // Wait for the radio button's label to appear
-        await page.waitForSelector('label[for="form:schlagwortOptionen:0"]', { timeout: 5000 });
-
-        // Click the label to select the radio button
-        await page.evaluate(() => {
-          const label = document.querySelector<HTMLLabelElement>(
-            'label[for="form:schlagwortOptionen:0"]'
-          );
-          if (label) {
-            label.click();
-          }
-        });
-
-        console.log('Radio button clicked successfully!');
-      } catch (error) {
-        console.error('Failed to find or click the radio button:', error);
-      }
-
-      await this.clickFindButton(page, resultsLimitArg);
-
-      const businessRecords = await this.waitForResults(page);
-
-      // Parse out the registration info
-      for (const record of businessRecords) {
-        if (record.registrationId) {
-          record.germanParsedRegistration = await this.parseGermanRegistration(
-            record.registrationId
-          );
-        }
-      }
-
-      await page.close();
-      return businessRecords;
-    }, 60000);
-  }
-
-  /**
-   * Search for a specific company (known register type/number/court),
-   * then click on an element that triggers a file download.
-   */
-  public async getSpecificCompany(companyArg: BusinessRecord['data']['germanParsedRegistration']) {
-    return this.asyncExecutionStack.getExclusiveExecutionSlot(async () => {
-      if (!companyArg?.type || !companyArg.number || !companyArg.court) {
-        throw new Error('A complete parsed German registration is required.');
-      }
-
-      const page = await this.getNewPage();
-      await this.navigateToPage(page, 'Normal search');
-      await page.waitForSelector('#form\\:schlagwoerter', { timeout: 5000 });
-
-      // 1) Type of Register (e.g. HRB, HRA, etc.)
-      await page.waitForSelector('#form\\:registerArt_label');
-      await page.click('#form\\:registerArt_label');
-      await page.waitForSelector('#form\\:registerArt_items');
-      await page.evaluate((type) => {
-        const options = Array.from(document.querySelectorAll('#form\\:registerArt_items li'));
-        const targetOption = options.find((option) => option.textContent?.trim() === type);
-        (targetOption as HTMLElement)?.click();
-      }, companyArg.type);
-
-      // 2) Register number
-      await page.waitForSelector('#form\\:registerNummer');
-      await page.type('#form\\:registerNummer', companyArg.number);
-
-      // 3) Register court
-      await page.waitForSelector('#form\\:registergericht_label');
-      await page.click('#form\\:registergericht_label');
-      await page.waitForSelector('#form\\:registergericht_items');
-      await page.evaluate((court) => {
-        const options = Array.from(document.querySelectorAll('#form\\:registergericht_items li'));
-        const targetOption = options.find((option) => option.textContent?.trim() === court);
-        (targetOption as HTMLElement)?.click();
-      }, companyArg.court);
-
-      // Click 'Find'
-      await this.clickFindButton(page);
-
-      // Optionally grab the results, just for logging
-      const businessRecords = await this.waitForResults(page);
-      console.log(businessRecords);
-
-      const files: plugins.smartfile.SmartFile[] = [];
-
-      // download files
-      files.push(await this.downloadFile(page, 'SI'));
-      files.push(await this.downloadFile(page, 'AD'));
-
-      // At this point, the file should have been downloaded automatically
-      // to the path specified by `Page.setDownloadBehavior`
-      await page.close();
-
-      return {
-        businessRecords,
-        files,
-      };
-    }, 60000);
-  }
-
-  /**
-   * get specific company by full name
-   */
-  public async getSpecificCompanyByName(companyNameArg: string) {
-    const businessRecords = await this.searchCompany(companyNameArg, 1);
-    const result = this.getSpecificCompany(businessRecords[0].germanParsedRegistration);
-    return result;
-  }
-}