Parser API-Offline Browser-API für vCard-Parsing

Die Parser API ist eine leistungsstarke, vollständig offline funktionierende Browser-API für das Parsen von Visitenkarten, Impressum-Daten und vCard-Formaten. Mit drei verschiedenen Zugriffsmethoden können Sie die API direkt aus der Browser-Konsole, über Cross-Tab-Kommunikation oder als direkten Import in Ihre Anwendung nutzen.

Was ist die Parser API?

Die Parser API stellt alle Parsing-Funktionen von kontakte.me als programmierbare Schnittstelle zur Verfügung. Sie können damit:

• Impressum-Texte in strukturierte vCards umwandeln
• OCR-Ergebnisse mit räumlichen Daten verarbeiten
• vCard-Strings in JavaScript-Objekte parsen
• Mehrere vCards aus einem Text extrahieren

Besonders wichtig: Die gesamte API funktioniert vollständig offline und benötigt keine externen Server oder Cloud-Dienste.

Zugriffsmethoden

1. Window API (Browser-Konsole)

Die einfachste Methode: Öffnen Sie die Browser-Konsole (F12) und nutzen Sie window.vcardAPI:

// Einfaches Beispiel
const vcard = window.vcardAPI.parseImpressum (`
Musterfirma GmbH
Max Mustermann
Hauptstraße 123
10115 Berlin
Telefon: +49 30 12345678
E-Mail: info@musterfirma.de
`);

console.log (vcard);

Ausgabe: Ein vollständiger vCard 3.0 String mit strukturierten Kontaktdaten.

Praktische Anwendungsfälle

Bookmarklet erstellen:

javascript:(function (){
  const text = prompt ('Impressum-Text eingeben:');
  const vcard = window.vcardAPI.parseImpressum (text);
  console.log (vcard);
  alert ('vCard erstellt! Siehe Konsole.');
})();

Browser-Extension:

// In Ihrer Extension
chrome.tabs.executeScript ({
  code: 'window.vcardAPI.parseImpressum (document.body.innerText);'
});

2. PostMessage API (Cross-Tab-Kommunikation)

Ideal für die Kommunikation zwischen verschiedenen Tabs, iFrames oder Domains:

// Request senden
window.postMessage ({
  type: 'VCARD_API_REQUEST',
  id: 'unique-id-123',
  method: 'parseImpressum',
  data: 'Ihre Impressum-Daten hier...'
}, '*');

// Response empfangen
window.addEventListener ('message', (event) => {
  if (event.data.type === 'VCARD_API_RESPONSE') {
    if (event.data.success) {
      console.log ('Erfolg:', event.data.result);
    } else {
      console.error ('Fehler:', event.data.error);
    }
  }
});

Response-Format

{
  type: 'VCARD_API_RESPONSE',
  id: 'unique-id-123',       // Ihre Request-ID
  success: true,             // true bei Erfolg, false bei Fehler
  result?: any,              // Ergebnis (bei success: true)
  error?: string             // Fehlermeldung (bei success: false)
}

Anwendungsfall: Multi-Tab-Anwendung

// Tab A: Daten sammeln
const impressumText = document.querySelector ('.impressum').innerText;
localStorage.setItem ('impressumData', impressumText);

// Tab B: Parser-Tab laden und verarbeiten
window.postMessage ({
  type: 'VCARD_API_REQUEST',
  id: 'batch-process-1',
  method: 'parseImpressum',
  data: localStorage.getItem ('impressumData')
}, '*');

3. Direct Import (React/TypeScript)

Für interne Anwendungslogik:

import { parserAPI } from '@/utils/parserAPI';

const BusinessCardScanner = () => {
  const [result, setResult] = useState ('');

  const handleScan = async (ocrData: any[]) => {
    const vcard = parserAPI.parseSpatial (ocrData);
    setResult (vcard);
  };

  return (
    <div>
      <button onClick={() => handleScan (ocrLines)}>
        Scan verarbeiten
      </button>
      <pre>{result}</pre>
    </div>
  );
};

Verfügbare Methoden

parseImpressum (text: string): string

Parst Impressum-Texte oder Visitenkarten-Inhalte in vCard-Format.

Parameter:

• text (string): Unstrukturierter Text aus Impressum oder Visitenkarte

Rückgabe: vCard 3.0 String

Beispiel:

const vcard = window.vcardAPI.parseImpressum (`
Christian Kohl Veranstaltungstechnik e.K.
Am Behälterberg 16
91074 Herzogenaurach
Telefon: +49 911 7230 174 0
E-Mail: info@motion-sales.de
`);

Unterstützte Formate:

• ✅ Deutsche, österreichische und schweizerische Adressen
• ✅ Mehrsprachige Labels (Telefon/Phone, E-Mail/Email, etc.)
• ✅ Duplikat-Ländercode-Bereinigung (AT AT → AT)
• ✅ Komplexe Rechtsformen (GmbH & Co. KG, e.U., etc.)
• ✅ Bidirektionale Namenerkennung (Vorname Nachname & Nachname Vorname)

parseSpatial (ocrLines: Array): string

Parst OCR-Ergebnisse mit räumlichen/Bounding-Box-Daten.

Parameter:

• ocrLines (Array): Array von Objekten mit text und bbox Properties

Rückgabe: vCard 3.0 String

Beispiel:

const ocrData = [
  { text: "Firma GmbH", bbox: { x0: 100, y0: 50, x1: 300, y1: 80 } },
  { text: "Max Mustermann", bbox: { x0: 100, y0: 90, x1: 300, y1: 120 } },
  // ...
];

const vcard = window.vcardAPI.parseSpatial (ocrData);

parseVCard (vcard: string): VCardData | null

Parst einen vCard-String in ein JavaScript-Objekt.

Parameter:

• vcard (string): vCard-String (beliebige Version)

Rückgabe: VCardData-Objekt oder null bei Fehler

Beispiel:

const vcardString = `BEGIN:VCARD
VERSION:3.0
FN:Max Mustermann
TEL:+49301234567
END:VCARD`;

const data = window.vcardAPI.parseVCard (vcardString);
console.log (data.fn); // "Max Mustermann"
console.log (data.tel); // ["+49301234567"]

extractVCards (content: string): string[]

Extrahiert mehrere vCards aus einem Text.

Parameter:

• content (string): Text mit möglicherweise mehreren vCards

Rückgabe: Array von vCard-Strings

Beispiel:

const multiVcard = `BEGIN:VCARD
VERSION:3.0
FN:Person 1
END:VCARD
Zwischentext
BEGIN:VCARD
VERSION:3.0
FN:Person 2
END:VCARD`;

const vcards = window.vcardAPI.extractVCards (multiVcard);
console.log (vcards.length); // 2

Erweiterte Anwendungsfälle

Batch-Verarbeitung von Impressum-Daten

const impressumUrls = [
  'https://example1.com/impressum',
  'https://example2.com/impressum',
  // ...
];

const vcards = [];

for (const url of impressumUrls) {
  const response = await fetch (url);
  const html = await response.text ();
  const parser = new DOMParser ();
  const doc = parser.parseFromString (html, 'text/html');
  const text = doc.body.innerText;
  
  const vcard = window.vcardAPI.parseImpressum (text);
  vcards.push (vcard);
}

// Alle vCards zusammenführen
const combinedVCard = vcards.join ('\n');
console.log (`${vcards.length} Kontakte verarbeitet`);

Automatische Lead-Erfassung auf Messen

// Integration mit Scanner-App
async function scanBusinessCard (imageData) {
  // 1. OCR durchführen (z.B. mit Tesseract.js)
  const ocrResult = await performOCR (imageData);
  
  // 2. Mit Parser API verarbeiten
  const vcard = window.vcardAPI.parseSpatial (ocrResult);
  
  // 3. In CRM speichern
  await saveToCRM (vcard);
  
  return vcard;
}

Chrome Extension für Impressum-Parser

// content_script.js
chrome.runtime.onMessage.addListener ((request, sender, sendResponse) => {
  if (request.action === 'parseImpressum') {
    const impressumText = document.querySelector ('.impressum')?.innerText;
    
    if (impressumText && window.vcardAPI) {
      const vcard = window.vcardAPI.parseImpressum (impressumText);
      sendResponse ({ success: true, vcard });
    } else {
      sendResponse ({ success: false, error: 'Kein Impressum gefunden' });
    }
  }
});

Fehlerbehandlung

Die API wirft Fehler bei ungültigen Eingaben:

try {
  const vcard = window.vcardAPI.parseImpressum ('');
  console.log (vcard);
} catch (error) {
  console.error ('Parser-Fehler:', error.message);
}

Bei PostMessage-Requests werden Fehler in der Response zurückgegeben:

window.addEventListener ('message', (event) => {
  if (event.data.type === 'VCARD_API_RESPONSE') {
    if (!event.data.success) {
      console.error ('API-Fehler:', event.data.error);
    }
  }
});

Performance & Best Practices

Offline-First

Die gesamte API läuft im Browser ohne externe Anfragen:

• ✅ Keine Netzwerk-Latenz
• ✅ Funktioniert ohne Internetverbindung
• ✅ DSGVO-orientiert (keine Cloud-Verarbeitung)

Optimierung

// ❌ Ineffizient: Mehrfache Verarbeitung desselben Texts
for (let i = 0; i < 100; i++) {
  const vcard = window.vcardAPI.parseImpressum (text);
}

// ✅ Effizient: Einmalige Verarbeitung, Ergebnis cachen
const vcard = window.vcardAPI.parseImpressum (text);
const cached = vcard; // Wiederverwendung

Sicherheit

PostMessage-Validierung:

window.addEventListener ('message', (event) => {
  // Wichtig: Origin validieren in Produktionsumgebung
  if (event.origin !== 'https://trusted-domain.com') {
    return;
  }
  
  if (event.data.type === 'VCARD_API_REQUEST') {
    // Verarbeiten...
  }
});

TypeScript-Unterstützung

Vollständige TypeScript-Definitionen verfügbar:

import type { ParserAPI, APIRequest, APIResponse } from '@/utils/parserAPI';

const api: ParserAPI = window.vcardAPI;

// Type-safe Request
const request: APIRequest = {
  type: 'VCARD_API_REQUEST',
  id: 'req-1',
  method: 'parseImpressum',
  data: 'text...'
};

// Type-safe Response Handler
const handleResponse = (response: APIResponse) => {
  if (response.success) {
    console.log (response.result);
  }
};

API-Status prüfen

// Verfügbarkeit prüfen
if (window.vcardAPI) {
  console.log ('Parser API verfügbar');
  console.log ('Version:', window.vcardAPI.version);
} else {
  console.error ('Parser API nicht geladen');
}

Interaktive Dokumentation

Besuchen Sie /api-docs für:

• 🎯 Live-Demo mit Beispiel-Daten
• 📋 Interaktive Code-Beispiele
• 📥 Copy-to-Clipboard für alle Snippets
• ✅ Echtzeit-API-Status

Technische Details

Implementierung:

• Vollständig in TypeScript geschrieben
• Nutzt WASM für performantes vCard-Parsing
• Event-basierte PostMessage-Architektur
• Automatische Initialisierung beim App-Start

Browser-Kompatibilität:

• Chrome/Edge: ✅ Vollständig unterstützt
• Firefox: ✅ Vollständig unterstützt
• Safari: ✅ Vollständig unterstützt

FAQ

Q: Werden meine Daten an Server gesendet?
A: Nein. Die gesamte Verarbeitung erfolgt lokal im Browser. Keine Daten verlassen Ihren Computer.

Q: Funktioniert die API offline?
A: Ja. Nach dem initialen Laden der Seite funktioniert die API vollständig offline.

Q: Kann ich die API kommerziell nutzen?
A: Ja, die API steht zur Verfügung für alle Nutzer von kontakte.me.

Q: Welche Sprachen werden unterstützt?
A: Die Parser unterstützen deutsche, englische, österreichische und schweizerische Adressformate.

Q: Wie groß ist die maximale Text-Länge?
A: Es gibt keine feste Grenze, aber für optimale Performance empfehlen wir Texte unter 10.000 Zeichen.

Weiterführende Ressourcen

• vCard-Format – Details zum vCard-Standard
• vCard-Kompatibilitätsprofil – Feldabdeckung & Mapping
• API-Dokumentation – Interaktive Dokumentation

Zusammenfassung

Die Parser API ermöglicht:

• ✅ Offline-Parsing von Visitenkarten und Impressum-Daten
• ✅ Drei flexible Zugriffsmethoden (Window, PostMessage, Import)
• ✅ Vollständige TypeScript-Unterstützung
• ✅ DSGVO-orientierte Verarbeitung ohne Cloud
• ✅ Hohe Performance durch WASM-Integration

Starten Sie direkt in der interaktiven Dokumentation!