npm package: @marcmeese/n8n-nodes-communityapi-doc-client
Description: Community API DOC Server nodes for n8n
Latest version: 0.3.7

# n8n Nodes für Community API DOC Server

Dieses Paket stellt n8n-Nodes für die Integration mit dem Community API DOC Server bereit.

**Wichtig:** Zur Nutzung der Nodes ist ein Account in der AI Community (https://ki-communities.de) zwingend notwendig, da dadurch der Zugang auf dem DOC Server erstellt wird.

## Installation

In n8n Settings → Community Nodes:

```
@marcmeese/n8n-nodes-communityapi-doc-client
```

## Konfiguration

### Authentifizierung einrichten

1. Gehe zu n8n → Credentials → New
2. Wähle "CommunityAPI - DOC Server"
3. Gib deinen API-Key ein
4. Teste die Verbindung

## Verfügbare Nodes

### 📋 Basis-Funktionen

#### Get User Info

Ruft Benutzerinformationen vom DOC Server ab.

**Parameter:** Keine  
**Output:** Benutzerinformationen als JSON

#### Get Job

Ruft Details zu einem spezifischen Job ab.

**Parameter:**

- `Job ID` (string): Die ID des abzufragenden Jobs

**Output:** Job-Details als JSON

#### Download Job

Lädt die Ergebnisdateien eines abgeschlossenen Jobs herunter.

**Parameter:**

- `Job ID` (string): ID des herunterzuladenden Jobs
- `Output Folder` (string): Zielordner für Downloads
- `Basename` (string, optional): Basis-Dateiname
- `Keep Filenames` (boolean): Original-Dateinamen beibehalten

**Output:** Liste der heruntergeladenen Dateipfade

---

### 📤 Datei-Upload

#### Upload File

Lädt eine einzelne lokale Datei auf den DOC Server hoch.

**Parameter:**

- `Local File Path` (string): Pfad zur lokalen Datei

**Funktionsweise:**

1. Fordert eine Presigned URL vom Server an
2. Lädt die Datei direkt auf den Storage hoch
3. Gibt die File-ID zurück

**Output:**

```json
{
	"file_id": "uuid-der-datei",
	"filename": "original-dateiname.pdf"
}
```

**Beispiel:**

```
/home/user/documents/report.pdf → file_id: "abc-123-def"
```

#### Upload Files (Batch)

Lädt mehrere lokale Dateien parallel auf den DOC Server hoch.

**Parameter:**

- `Local File Paths` (string[]): Pfade zu den lokalen Dateien

**Funktionsweise:**

1. Fordert Batch Presigned URLs für alle Dateien an
2. Lädt alle Dateien parallel hoch (schneller als einzeln)
3. Gibt alle File-IDs zurück

**Output:**

```json
{
	"presigned": [
		{
			"file_id": "uuid-1",
			"filename": "file1.pdf"
		},
		{
			"file_id": "uuid-2",
			"filename": "file2.docx"
		}
	]
}
```

**Beispiel:**

```
["/path/to/file1.pdf", "/path/to/file2.docx"] →
{presigned: [{file_id: "abc-123"}, {file_id: "def-456"}]}
```

---

### 📄 Dokument-Verarbeitung

#### Document Converter

Konvertiert Dokumente zwischen verschiedenen Formaten.

**Parameter:**

- `Input Document Paths` (string[]): Pfade zu Dokumenten (UUID, URL oder lokaler Pfad)
- `Target Format` (dropdown): Zielformat
- `Callback URL` (string, optional): URL für Callback
- `Callback Payload` (JSON, optional): Zusätzliche Daten

**Unterstützte Eingabe-Formate:**

- **Office-Dokumente:** doc, docx, ppt, pptx, xls, xlsx, odt, rtf
- **Text/Markup:** txt, md, html, htm
- **Daten:** json, xml, yaml, yml, csv
- **Config/Logs:** log, ini, cfg, properties
- **PDF:** pdf

**Unterstützte Ausgabe-Formate:**

**Office:**

- PDF
- Word: DOCX, DOC
- PowerPoint: PPTX, PPT
- Excel: XLSX, XLS, CSV
- OpenDocument: ODT
- Rich Text: RTF

**Text/Markup:**

- Plain Text: TXT
- Markdown: MD
- Web: HTML, HTM

**Daten:**

- JSON
- XML
- YAML, YML

**Config:**

- LOG
- INI
- CFG
- Properties

**Bilder (aus PDF):**

- PNG
- JPG, JPEG

**Intelligente Eingabe-Verarbeitung:**

Der Document Converter akzeptiert verschiedene Input-Formate:

1. **File-ID (UUID)**: Von vorherigem Upload-Node

   ```
   "abc-123-def-456"
   ```

2. **HTTP(S) URL**: Direkter Download

   ```
   "https://example.com/document.pdf"
   ```

3. **Lokaler Pfad**: Automatischer Upload
   ```
   "/home/user/documents/report.docx"
   ```

**Workflow-Beispiele:**

```
Beispiel 1: Lokale Datei konvertieren
[Local File] → DocumentConverter → DownloadJob

Beispiel 2: Mit Upload-Node
UploadFile → DocumentConverter(file_id) → DownloadJob

Beispiel 3: URL direkt konvertieren
DocumentConverter(https://...) → DownloadJob

Beispiel 4: Batch-Verarbeitung
UploadFiles → DocumentConverter(multiple file_ids) → DownloadJob
```

**Output:**

```json
{
	"job_id": "job-uuid",
	"status": "pending",
	"created_at": "2026-01-22T12:00:00Z"
}
```

---

## Workflow-Beispiele

### Beispiel 1: Einfache Konvertierung

```
1. Upload File (/path/to/document.docx)
   ↓ {file_id: "abc-123"}
2. Document Converter (file_id: "abc-123", target: "pdf")
   ↓ {job_id: "job-456"}
3. Download Job (job_id: "job-456", output: "/downloads/")
   ↓ ["/downloads/document.pdf"]
```

### Beispiel 2: Batch-Konvertierung

```
1. Upload Files ([file1.doc, file2.docx, file3.txt])
   ↓ {presigned: [{file_id: "a"}, {file_id: "b"}, {file_id: "c"}]}
2. Document Converter (file_ids: ["a", "b", "c"], target: "pdf")
   ↓ {job_id: "job-789"}
3. Download Job (job_id: "job-789")
   ↓ [file1.pdf, file2.pdf, file3.pdf]
```

### Beispiel 3: URL-basierte Konvertierung

```
1. Document Converter (input: "https://example.com/report.xlsx", target: "csv")
   ↓ {job_id: "job-xyz"}
2. Download Job (job_id: "job-xyz")
   ↓ [report.csv]
```

### Beispiel 4: Mit Callback

```
1. Upload File + Document Converter (mit callback_url)
   ↓ {job_id: "job-abc"}
2. [Job läuft im Hintergrund]
3. Webhook empfängt Callback mit Ergebnis
```

---

## Entwicklung

### Build-Prozess

```bash
# Dependencies installieren
npm install

# TypeScript kompilieren + Icons kopieren
npm run build

# Development Mode (Watch)
npm run dev
```

### Projektstruktur

```
src/
├── config/
│   └── endpoints.ts
├── credentials/
│   └── CommunityAPIDOCServer.credentials.ts
├── nodes/
│   └── CommunityAPIDOCServer/
│       ├── GetUserInfo/
│       ├── GetJob/
│       ├── DownloadJob/
│       ├── UploadFile/
│       ├── UploadFiles/
│       └── DocumentConverter/
├── utils/
│   ├── apiRequests.ts
│   ├── fileUploads.ts
│   └── inputProcessing.ts
└── index.ts
```

### API-Endpunkte

- **Auth:** `https://auth.marcmeese.de`
- **DOC Server:** `https://doc.marcmeese.de` (Note: In der aktuellen Implementierung wird `ai.marcmeese.de` verwendet)

## Fehlerbehebung

### Häufige Probleme

1. **Authentication Failed**
   - API-Key im Account überprüfen
   - Credentials in n8n neu erstellen

2. **File Not Found (Upload)**
   - Absolute Pfade verwenden
   - Datei-Berechtigungen prüfen
   - Bei Windows: Pfade mit `/` statt `\`

3. **Unsupported File Format**
   - Liste der unterstützten Formate prüfen
   - Dateiendung muss korrekt sein

4. **Upload Failed**
   - Datei-Größe prüfen (Max. Limit beachten)
   - Internet-Verbindung prüfen
   - Presigned URL könnte abgelaufen sein (läuft automatisch ab)

5. **Conversion Failed**
   - Eingabe-Format wird unterstützt?
   - Ziel-Format für diese Eingabe möglich?
   - Bei PDF → Bild: Nur erste Seite wird konvertiert

### Debug-Modus

Setze n8n in den Debug-Modus für detaillierte Logs:

```bash
export N8N_LOG_LEVEL=debug
n8n start
```

## Callback-System

Document Converter unterstützt Callbacks für asynchrone Verarbeitung:

**Callback URL**: Webhook-URL, die nach Job-Abschluss aufgerufen wird  
**Callback Payload**: Benutzerdefinierte Daten, die mit dem Callback zurückgegeben werden

**Beispiel-Payload:**

```json
{
	"parameters": [
		{ "key": "workflow_id", "value": "12345" },
		{ "key": "user_email", "value": "user@example.com" }
	]
}
```

**Callback-Response:**

```json
{
	"job_id": "job-uuid",
	"status": "completed",
	"result_files": ["file1.pdf", "file2.pdf"],
	"callback_payload": {
		"workflow_id": "12345",
		"user_email": "user@example.com"
	}
}
```

## Best Practices

1. **Batch-Upload nutzen**: Für mehrere Dateien immer `Upload Files` statt mehrfach `Upload File`
2. **File-IDs wiederverwenden**: Upload einmal, konvertiere mehrfach
3. **Callbacks verwenden**: Bei großen Dateien/langen Jobs
4. **Error Handling**: Immer prüfen, ob Upload/Conversion erfolgreich war
5. **Temp-Dateien löschen**: Nach Download die lokalen Temp-Dateien aufräumen

## Support

Bei Problemen oder Fragen:

1. Überprüfe die Logs in n8n
2. Teste die API-Endpoints manuell mit curl/Postman
3. Kontaktiere den Support über https://ki-communities.de

## Lizenz

MIT - Siehe LICENSE.md für Details.