@drdoc-com/pi-drdoc 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,68 @@
+# Pi Plugin for Dr.DOC
+
+An integration plugin Package for the **Pi Agent** (`pi.dev`) ecosystem to interact seamlessly with the [**Dr.DOC Document Management System** \(DMS/ECM\)](drdoc.com/node/de/products/web). 
+
+This plugin allows the Pi Agent to query Dr.DOC archives, fetch document blobs, store files locally, generate direct web links, and display inline document previews.
+
+---
+
+## System Architecture & Integration Directions
+
+The integration between Pi Agent and Dr.DOC is split into two primary operational directions:
+
+### 1. Pi → Dr.DOC (This Plugin)
+This plugin enables the **Pi Agent** to make outgoing API calls to **Dr.DOC**. The agent uses these tool functions to search archives, retrieve documents, save them locally, and process binary/image data.
+
+### 2. Dr.DOC → Pi (OpenAI API Wrapper)
+To allow **Dr.DOC** (or external tools) to send requests to Pi using the standard OpenAI API format, the `@drdoc-com/pi-openai-api-wrapper` package can be used.
+
+* **GitHub Repository:** [github.com/drdoc-com/pi-openai-api-wrapper](https://github.com/drdoc-com/pi-openai-api-wrapper)
+* **Pi Package Registry:** [pi.dev/packages/@drdoc-com/pi-openai-api-wrapper](https://pi.dev/packages/@drdoc-com/pi-openai-api-wrapper)
+* **npm Package:** [npmjs.com/package/@drdoc-com/pi-openai-api-wrapper](https://www.npmjs.com/package/@drdoc-com/pi-openai-api-wrapper)
+
+---
+
+## Features
+
+* **Document Retrieval:** Fetches document blobs and metadata from Dr.DOC using archive names and record IDs.
+* **Safe Local Storage:** Automatically saves retrieved files to a reliable user directory (`~/.drdoc/downloads/`), avoiding conflicts with host extension directories.
+* **Inline Image Previews:** Generates Base64 data URLs for image files (`image/*`), enabling direct rendering in the Pi Agent interface.
+* **Direct Web URL Generation:** Creates browser-accessible URLs for fetched documents (`https://drdoc.com/model/document?action=get&...`).
+* **Robust Error Handling:** Checks HTTP status codes (`response.ok`) and handles binary buffers cleanly.
+
+---
+
+## Installation
+
+Install the package via npm or directly into your Pi extension environment:
+```bash
+pi install npm:@drdoc-com/pi-drdoc
+```
+
+Or via GitHub:
+```bash
+pi install git:https://github.com/drdoc-com/pi-drdoc
+```
+
+---
+
+## Configuration
+
+The plugin utilizes configuration options supplied by the Dr.DOC client or environment variables.
+
+### Environment Variables
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `DRDOC_BASE_URL` | Base URL of the Dr.DOC instance | `https://drdoc.com` |
+| `DRDOC_CONFIG_DIR` (alt. `PI_CONFIG_DIR`) | Custom directory for config files | `~/.pi/agent` |
+| `DRDOC_DOWNLOAD_DIR` | Custom directory for downloaded files | `~/.drdoc/downloads` |
+| `DRDOC_IGNORE_SSL` | Ignore TLS/SSL Errors (Set `NODE_TLS_REJECT_UNAUTHORIZED=0`) | `` |
+| `DRDOC_DEBUG` | Enable Debugging | `` |
+
+---
+
+## License
+
+This project is licensed under the Apache License 2.0.
+Dr.DOC DMS is licensed is under proprietary License.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@drdoc-com/pi-drdoc",
+  "version": "1.0.0",
+  "description": "Dr.DOC DMS Integration Package for PI Agent",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["pi-package", "pi-agent", "drdoc", "rest-api", "skill", "dms", "Dr.DOC"],
+  "private": false,
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/drdoc-com/pi-drdoc.git"
+  },
+  "author": "Dr.DOC GmbH, DE-80802 Munich",
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^26.2.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}
+

package/src/drdoc-client.ts

@@ -0,0 +1,468 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+import { URLSearchParams } from "url";
+
+/**
+ * Interface für Standard-Antworten der Dr.DOC REST API
+ */
+export interface DrDocResponse<T = any> {
+  HasError: boolean;
+  Error?: {
+    Message: string;
+    InternalMessage?: string;
+  };
+  Count?: number;
+  CountTotal?: number;
+  Result?: T;
+  $ModelType?: string;
+}
+
+/**
+ * Konfiguration für den DrDOC Client
+ */
+export interface DrDocConfig {
+  baseUrl: string;
+  username?: string;
+  password?: string;
+  totp?: string;
+  /**
+   * Deaktiviert die Zertifikatsprüfung für selbstsignierte HTTPS-Zertifikate.
+   */
+  ignoreSSL?: boolean;
+  sessionCookie?: string;
+  authHeader?: string;
+}
+
+/**
+ * Hilfsmethode zum sicheren Abrufen des UI-Objekts aus dem globalen Kontext (globalThis).
+ * Verhindert ReferenceError-Ausnahmen bei nicht deklarierten Variablen.
+ */
+function getGlobalUI(): any {
+  const g = globalThis as any;
+  return g.ctx?.ui || g.pi?.ui;
+}
+
+export function msgLog(...args: any[]) {
+  console.log(...args);
+  const ui = getGlobalUI();
+  if (typeof ui?.notify === "function") {
+    ui.notify(...args);
+  }
+}
+
+export function msgInfo(message: string) {
+  const ui = getGlobalUI();
+  if (typeof ui?.notify === "function") {
+    ui.notify(message, "info");
+  } else {
+    console.log(message);
+  }
+}
+
+export function msgError(message: string) {
+  const ui = getGlobalUI();
+  if (typeof ui?.notify === "function") {
+    ui.notify(message, "error");
+  } else {
+    console.error(message);
+  }
+}
+
+/**
+ * Liefert den absoluten Pfad zum globalen Einstellungs-Verzeichnis (~/.pi/agent/).
+ */
+export function getGlobalSettingsDir(): string {
+  // Berücksichtigung von benutzerdefinierten Pfaden über Umgebungsvariablen
+  if (process.env.DRDOC_CONFIG_DIR) {
+    return process.env.DRDOC_CONFIG_DIR;
+  }
+  if (process.env.PI_CONFIG_DIR) {
+    return process.env.PI_CONFIG_DIR;
+  }
+  return path.join(os.homedir(), ".pi", "agent");
+  // path.resolve(process.cwd()
+}
+
+/**
+ * Client-Klasse für die Interaktion mit der Dr.DOC REST API.
+ * Verwaltet Sitzungscookies und führt HTTP-Requests aus.
+ */
+export class DrDocClient {
+  private config: DrDocConfig;
+  private storageFilePath: string;
+  //private sessionCookie: string | null = null;
+  //private authHeader: string | null = null;
+
+  constructor(config: DrDocConfig) {
+    this.config = config; //{ ...config };
+    this.storageFilePath = path.join(getGlobalSettingsDir(), ".drdoc-session.json");
+
+    // Vorhandene Anmeldedaten beim Instanziieren aus der JSON-Datei laden
+    this.loadCredentials();
+
+    // Basis-Konfiguration und HTTP-Einstellungen anwenden
+    this.applyConfig();
+
+    if (process.env.DRDOC_DEBUG)
+      msgLog('Ctor', this.config);
+  }
+
+  public getConfig(): any {
+    return this.config;
+  }
+
+  /**
+   * Wendet die Eigenschaften aus 'config' auf die Instanzvariablen an.
+   */
+  private applyConfig(): void {
+    if (!this.config.baseUrl) {
+      this.config.baseUrl = process.env.DRDOC_BASE_URL;
+    }
+    if (!this.config.baseUrl) {
+      throw new Error("DrDocClient erfordert eine gültige 'baseUrl' in der Konfiguration.");
+    }
+
+    if (this.config.ignoreSSL || process.env.DRDOC_IGNORE_SSL) {
+      process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+    }
+
+    this.config.baseUrl = this.config.baseUrl.replace(/\/$/, "");
+
+    if (this.config.username && this.config.password) {
+      const authStr = `${this.config.username}:${this.config.password}`;
+      this.config.authHeader = `Basic ${Buffer.from(authStr).toString("base64")}`;
+    }
+  }
+
+  /**
+   * Liest gespeicherte Anmeldedaten als DrDocConfig aus der JSON-Datei aus, sofern vorhanden.
+   */
+  private loadCredentials(): void {
+    try {
+      if (fs.existsSync(this.storageFilePath)) {
+        const fileContent = fs.readFileSync(this.storageFilePath, "utf-8");
+        const savedConfig: DrDocConfig = JSON.parse(fileContent);
+
+        // Gespeicherte Werte mit den übergebenen Konfigurationswerten zusammenführen
+        this.config = {
+          ...this.config,
+          ...savedConfig,
+        };
+      }
+    } catch (error) {
+      console.warn("Gespeicherte Anmeldedaten konnten nicht geladen werden:", error);
+    }
+  }
+
+  /**
+   * Speichert das DrDocConfig-Objekt als JSON-Datei ab.
+   */
+  private saveCredentials(): void {
+    try {
+      const dataToSave = JSON.stringify(this.config, null, 2);
+      fs.writeFileSync(this.storageFilePath, dataToSave, "utf-8");
+      msgLog('DD Anmeldedaten wurden gespeichert unter: ', this.storageFilePath);
+    } catch (error) {
+      throw new Error(`Fehler beim Speichern der Anmeldedaten: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Erstellt Standard-Header inklusive Session-Cookie und Auth-Header
+   */
+  private getHeaders(additionalHeaders: Record<string, string> = {}): Record<string, string> {
+    const headers: Record<string, string> = { ...additionalHeaders };
+
+    if (this.config?.sessionCookie) {
+      headers["Cookie"] = this.config.sessionCookie;
+    } else if (this.config.authHeader) {
+      //headers["Authorization"] = this.config.authHeader;
+    }
+
+    return headers;
+  }
+
+  /**
+   * Speichert erhaltene Cookies (insbesondere 'uid' für User Sessions)
+   */
+  private processResponseCookies(response: Response): void {
+    const setCookie = response.headers.get("set-cookie");
+    if (setCookie) {
+      const match = setCookie.match(/uid=([^;]+)/);
+      if (match) {
+        this.config.sessionCookie = `uid=${match[1]}`;
+        // this.saveCredentials(this.config);
+      }
+    }
+  }
+
+  /**
+   * Hilfsmethode für GET-Anfragen
+   */
+  public async get<T = any>(endpoint: string, params: Record<string, any> = {}): Promise<DrDocResponse<T>> {
+    // Verwendung des URL-Objekts zur sauberen Zusammenführung von baseUrl und endpoint
+    const url = new URL(endpoint, this.config.baseUrl);
+
+    if (process.env.DRDOC_DEBUG)
+      msgLog("DD Get Head: ", endpoint, params, url);
+
+    // Befüllung der SearchParams
+    Object.entries(params).forEach(([key, val]) => {
+      if (val !== undefined && val !== null) {
+        if (Array.isArray(val)) {
+          // Umgang mit Arrays: Parameter mehrfach anhängen
+          val.forEach((item) => url.searchParams.append(key, String(item)));
+        } else if (typeof val === "object") {
+          url.searchParams.append(key, JSON.stringify(val));
+        } else {
+          url.searchParams.append(key, String(val));
+        }
+      }
+    });
+
+    const response = await fetch(url, {
+      method: "GET",
+      headers: this.getHeaders(),
+    });
+
+    this.processResponseCookies(response);
+    return (await response.json()) as DrDocResponse<T>;
+  }
+
+  /**
+   * Hilfsmethode für GET-Anfragen
+   */
+  public async getBlob<T = any>(endpoint: string, params: Record<string, any> = {}): Promise<Blob> {
+    // Verwendung des URL-Objekts zur sauberen Zusammenführung von baseUrl und endpoint
+    const url = new URL(endpoint, this.config.baseUrl);
+
+    if (process.env.DRDOC_DEBUG)
+      msgLog("DD Get Blob Head: ", endpoint, params, url);
+
+    // Befüllung der SearchParams
+    Object.entries(params).forEach(([key, val]) => {
+      if (val !== undefined && val !== null) {
+        if (Array.isArray(val)) {
+          // Umgang mit Arrays: Parameter mehrfach anhängen
+          val.forEach((item) => url.searchParams.append(key, String(item)));
+        } else if (typeof val === "object") {
+          url.searchParams.append(key, JSON.stringify(val));
+        } else {
+          url.searchParams.append(key, String(val));
+        }
+      }
+    });
+
+    const response = await fetch(url, {
+      method: "GET",
+      headers: this.getHeaders(),
+    });
+
+    this.processResponseCookies(response);
+
+    return response.blob();
+  }
+
+  /**
+   * Hilfsmethode für POST-Anfragen (Form URL-Encoded oder Multipart)
+   */
+  public async post<T = any>(endpoint: string, data: Record<string, any> = {}): Promise<DrDocResponse<T>> {
+    // Verwendung des URL-Objekts zur sauberen Zusammenführung von baseUrl und endpoint
+    const url = new URL(endpoint, this.config.baseUrl);
+
+    if (process.env.DRDOC_DEBUG)
+      msgLog("DD Post Head: ", endpoint, data, url);
+
+    const body = new URLSearchParams();
+    Object.entries(data).forEach(([key, val]) => {
+      if (val !== undefined && val !== null) {
+        if (Array.isArray(val)) {
+          // Umgang mit Arrays: Parameter mehrfach anhängen
+          val.forEach((item) => body.append(key, String(item)));
+        } else if (typeof val === "object") {
+          body.append(key, JSON.stringify(val));
+        } else {
+          body.append(key, String(val));
+        }
+      }
+    });
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: this.getHeaders({
+        "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
+      }),
+      body: body.toString(),
+    });
+
+    this.processResponseCookies(response);
+    return (await response.json()) as DrDocResponse<T>;
+  }
+
+  // --- Endpoint: Benutzerverwaltung ---
+
+  public async signin(username?: string, password?: string, totp?: string): Promise<DrDocResponse> {
+    const user = username || this.config.username;
+    const pass = password || this.config.password;
+    const totpCode = totp || this.config.totp;
+
+    // Ausführung des API-Aufrufs zur Anmeldung
+    const response = await this.post("/user", {
+      action: "signin",
+      username: user,
+      password: pass,
+      totp: totpCode,
+    });
+
+    // Überprüfung auf erfolgreiche Anmeldung
+    if (response && !response.HasError) {
+      this.config.username = user;
+      this.config.password = pass;
+      if (totpCode) {
+        this.config.totp = totpCode;
+      }
+
+      // Aktualisierung der internen Variablen (Auth-Header etc.)
+      this.applyConfig();
+
+      // Dauerhaftes Speichern der gesamten DrDocConfig nach erfolgreichem Login
+      this.saveCredentials();
+
+      msgLog('DD: Sign in OK:', this.config);
+    }
+    else {
+
+      console.warn('DD: Sign in ERR:', this.config);
+    }
+
+    return response;
+  }
+
+  public async state(): Promise<DrDocResponse> {
+
+    // Ausführung des API-Aufrufs zur Anmeldung
+    const response = await this.post("/user", {
+      action: "status",
+    });
+
+    // Überprüfung auf erfolgreiche Anmeldung
+    if (response && !response.HasError) {
+      msgLog('DD: State OK:', this.config);
+      return true;
+    }
+    else {
+      msgError('DD: State ERR:', this.config);
+      return false;
+    }
+  }
+
+  public async signout(): Promise<DrDocResponse> {
+    return this.post("/user", { action: "signout" });
+  }
+
+  public async userStatus(): Promise<DrDocResponse> {
+    return this.post("/user", { action: "status" });
+  }
+
+  // --- Endpoint: Metadaten CRUD ---
+
+  public async getRecord(archive: string, id: string, idField?: string): Promise<DrDocResponse> {
+    return this.post("/model/crud", {
+      action: "get",
+      archive,
+      id,
+      id_field: idField,
+    });
+  }
+
+  public async createRecord(archive: string, value: Record<string, any>): Promise<DrDocResponse> {
+    return this.get("/model/crud", {
+      action: "create",
+      archive,
+      value,
+    });
+  }
+
+  public async updateRecord(archive: string, value: Record<string, any>): Promise<DrDocResponse> {
+    return this.post("/model/crud", {
+      action: "set",
+      archive,
+      value,
+    });
+  }
+
+  // VORSICHT!!
+  public async removeRecord(archive: string, id: string): Promise<DrDocResponse> {
+    return this.post("/model/crud", {
+      action: "remove",
+      archive,
+      id,
+    });
+  }
+
+  public async searchFields(
+    archive: string,
+    value: Record<string, any>,
+    options: { selection?: string; count?: number; start?: number } = {}
+  ): Promise<DrDocResponse> {
+    return this.post("/model/crud", {
+      action: "searchfields",
+      archive,
+      value,
+      ...options,
+    });
+  }
+
+  public async textRetrieval(
+    archive: string,
+    queryText: string,
+    options: { selection?: string; count?: number; start?: number } = {}
+  ): Promise<DrDocResponse> {
+    return this.post("/model/crud", {
+      action: "textretrieval",
+      archive,
+      value: queryText,
+      ...options,
+    });
+  }
+
+  // --- Endpoint: Document ---
+
+  public async getDocument(archive: string, id: string, idField?: string): Blob {
+    return this.getBlob("/model/document", {
+      action: "get",
+      archive,
+      id,
+      id_field: idField,
+    });
+  }
+
+  // --- Endpoint: Fieldselections / Fieldproperties ---
+
+  public async getFieldProperty(archive: string, type: string): Promise<DrDocResponse> {
+    return this.get("/model/fieldselection", {
+      action: "get-fieldproperty",
+      archive,
+      type,
+    });
+  }
+
+  public async getFieldSelection(archive: string, type: string, name: string): Promise<DrDocResponse> {
+    return this.get("/model/fieldselection", {
+      action: "get-fieldselection",
+      archive,
+      type,
+      name
+    });
+  }
+
+  public async listFieldSelections(archive: string, type: string): Promise<DrDocResponse> {
+    return this.get("/model/fieldselection", {
+      action: "list-fieldselections",
+      archive,
+      type,
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+import { drdocTools, getClient } from "./tools";
+import { DrDocClient, DrDocConfig, msgLog, msgInfo, msgError } from "./drdoc-client";
+
+
+/**
+ * Registriert Dr.DOC Tools und Slash Commands im PI Agent Kontext.
+ * 
+ * @param pi - PI Extension Context
+ */
+export default function (pi: any): void {
+  // Registrierung der Dr.DOC Werkzeuge
+  for (const tool of drdocTools) {
+    pi.registerTool(tool);
+  }
+
+  // Registrierung der Slash Commands
+
+  // Login
+  pi.registerCommand("drdoc_login", {
+    description: "Benutzer anmelden in Dr.DOC über die REST API und speichert die Session.",
+    handler: async (args: string, ctx: any) => {
+      // Entfernen leerer Strings nach dem String-Split
+      const parts = args.trim().split(/\s+/); //.filter(Boolean);
+      let [baseUrl, username, password, totp, ignoreSSL] = parts;
+
+      if (!baseUrl)
+        baseUrl = process.env.DRDOC_BASE_URL;
+
+      if (!baseUrl || !username || !password) {
+        msgError("Fehler: Syntax ist `/drdoc-login <baseUrl> <username> <password> <totp> <ignoreSSL:1,0>`");
+        return;
+      }
+
+      try {
+        //initializeDrDocClient({ baseUrl, username, password, totp, ignoreSSL });
+        //const client = new DrDocClient({ baseUrl, username, password, totp, ignoreSSL });
+        const client = await getClient({ baseUrl, username, password, totp, ignoreSSL: (ignoreSSL == '1' || ignoreSSL == 'true') });
+        if (process.env.DRDOC_DEBUG)
+          msgLog('Client: ', client);
+
+        const response = await client.signin(username, password, totp);
+
+        if (response.HasError) {
+          msgError(`Anmeldung fehlgeschlagen: ${response.Error?.Message}`);
+          return;
+        }
+
+        msgInfo("Erfolgreich an Dr.DOC angemeldet. Die Session ist aktiv.");
+      } catch (err: any) {
+        msgError(`Fehler bei der Verbindung: ${err.message}`);
+      }
+    },
+  });
+
+  // Login
+  pi.registerCommand("drdoc_logout", {
+    description: "Benutzer abmelden aus Dr.DOC.",
+    handler: async (args: string, ctx: any) => {
+      const client = await getClient();
+      client.signout();
+    }
+  });
+
+  if (process.env.DRDOC_DEBUG) {
+    // Test
+    pi.registerCommand("drdoc_log_test", {
+      description: "Log Test.",
+      handler: async (args: string, ctx: any) => {
+        const client = await getClient();
+        msgLog('Log Test: ', client);
+      }
+    });
+  }
+
+}
+
+export { DrDocClient, drdocTools };

package/src/tools.ts

@@ -0,0 +1,407 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+import { DrDocClient, DrDocConfig, msgLog, msgInfo, msgError } from "./drdoc-client";
+
+let clientInstance: DrDocClient | null = null;
+
+/**
+ * Hilfsfunktion zum Abrufen der initialisierten Instanz.
+ */
+export async function getClient(config: DrDocConfig = {} as DrDocConfig, force: Boolean = false): Promise<DrDocClient> {
+  if (!clientInstance || force) {
+    msgInfo('getClient: init instance');
+    clientInstance = new DrDocClient(config);
+    // Verbindung testen
+    if (await clientInstance.state())
+      msgInfo('getClient: state ok');
+    else {
+      throw new Error("getClient: DrDocClient ist nicht initialisiert. Bitte vorher den Befehl /drdoc-login ausführen.");
+    }
+  }
+  return clientInstance;
+}
+
+/**
+ * Hilfsfunktion zur Formatierung von Werkzeug-Antworten für das PI Framework.
+ * Garantiert stets ein definiertes 'content'-Array im Ergebnis.
+ */
+function formatToolResult(data: any, isError: boolean = false) {
+  const safeData = data ?? "";
+  const textContent = typeof safeData === "string" ? safeData : JSON.stringify(safeData, null, 2);
+  return {
+    content: [
+      {
+        type: "text",
+        text: isError ? `Fehler: ${textContent}` : textContent,
+      },
+    ],
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+/**
+ * Führt eine Werkzeug-Aktion sicher aus und fängt Ausnahmen ab,
+ * um stets ein valides PI-Antwortformat zu garantieren.
+ */
+async function safeExecute<T>(fn: () => Promise<T>) {
+  try {
+    const result = await fn();
+    return formatToolResult(result);
+  } catch (error: any) {
+    const errorMessage = error?.message || String(error);
+    msgError(errorMessage);
+    return formatToolResult(errorMessage, true);
+  }
+}
+
+/**
+ * Für Tool Execute Aufrufe für Client-basierte Werkzeuge.
+ * Überprüft das Vorhandensein aller Pflichtparameter, ruft die 'DrDocClient'-Instanz ab
+ * und führt die Ziel-Funktion innerhalb von 'safeExecute' aus.
+ *
+ * @param requiredParams Liste der erforderlichen Parameter-Namen.
+ * @param args Die vom Tool empfangenen Argumente.
+ * @param fn Auszuführende Funktion mit dem initialisierten Client und den Argumenten.
+ */
+export function safeExecuteClient<A extends Record<string, any> = Record<string, any>, T = any>(
+  requiredParams: (keyof A & string)[],
+  args: A | undefined,
+  fn: (client: DrDocClient, safeArgs: A) => Promise<T>
+) {
+  return safeExecute(async () => {
+    const safeArgs = (args || {}) as A;
+
+    // Überprüfung aller erforderlichen Parameter
+    const missing = requiredParams.filter(
+      (param) => safeArgs[param] === undefined || safeArgs[param] === null || safeArgs[param] === ""
+    );
+
+    if (missing.length > 0) {
+      throw new Error(`Fehlende Pflichtparameter: ${missing.join(", ")} müssen angegeben werden.`);
+    }
+
+    // Abruf der Client-Instanz und Ausführung der Logik
+    const client = await getClient();
+    return await fn(client, safeArgs);
+  });
+}
+
+/**
+ * Werkzeug-Definitionen für das PI Agent Framework.
+ */
+export const drdocTools = [
+  {
+    name: "drdoc_login_2",
+    description: "Meldet den Benutzer in Dr.DOC über die REST API an.",
+    parameters: {
+      type: "object",
+      properties: {
+        baseUrl: { type: "string", description: "Basis-URL der Dr.DOC Instanz (z. B. https://drdoc.com)" },
+        username: { type: "string", description: "Benutzername" },
+        password: { type: "string", description: "Passwort" },
+        totp: { type: "string", description: "TOTP F2A" },
+        ignoreSSL: { type: "boolean", description: "SSL-Zertifikatsprüfung ignorieren" },
+      },
+      required: ["baseUrl", "username", "password"],
+    },
+    execute: async (toolCallId: string, args?: { baseUrl?: string; username?: string; password?: string; totp?: string; ignoreSSL?: boolean }) => {
+      return safeExecute(async () => {
+        const safeArgs = args || {};
+        if (!safeArgs.baseUrl || !safeArgs.username || !safeArgs.password) {
+          throw new Error("Fehlende Pflichtparameter: baseUrl, username und password müssen angegeben werden.");
+        }
+        // getClient mit force: true zur Neu-Initialisierung
+        const client = await getClient({
+          baseUrl: safeArgs.baseUrl,
+          username: safeArgs.username,
+          password: safeArgs.password,
+          totp: safeArgs.totp,
+          ignoreSSL: safeArgs.ignoreSSL,
+        }, true);
+        return await client.signin(safeArgs.username, safeArgs.password, safeArgs.totp);
+      });
+    },
+  },
+  {
+    name: "drdoc_properties_fields",
+    description: "Liste aller Dr.DOC Felder (Feldnamen) im Dr.DOC Archiv. Diese Funktion **muss** vor 'drdoc_search_fields' aufgerufen werden.",
+    parameters: {
+      type: "object",
+      properties: {
+        archive: { type: "string", description: "Name des Dr.DOC Ziel-Archivs" },
+      },
+      required: ["archive"],
+    },
+    execute: async (toolCallId: string, args?: { archive?: string }) => {
+      if (process.env.DRDOC_DEBUG)
+        msgLog('drdoc_properties_fields:', args);
+      return safeExecuteClient(["archive"], args, async (client, safeArgs) => {
+        const defNameArray = ['STD_AI_INVOICE_IN', 'DD_FIELD_DESC', 'STD_FIELD_DESC'];
+        for (let defName of defNameArray) {
+          const fs = await client.getFieldSelection(safeArgs.archive, "IMPORT_ASCII", defName);
+          if (process.env.DRDOC_DEBUG)
+            msgLog('props:', fs);
+          if (!fs.HasError && fs.Result)
+            return fs.Result;
+        }
+        return {};
+      });
+    },
+  },
+  {
+    name: "drdoc_search_fields",
+    description: `Führt eine feldspezifische Suche (Feldsuche oder Filtersuche) in einem Dr.DOC Archiv durch.
+Du **musst** zuerst alle Dr.DOC Feldnamen durch 'drdoc_properties_fields' abrufen, und erst danach 'drdoc_search_fields', damit Du weißt in welchen Feldern Du suchen musst.
+
+Diese Suche sollte verwendet werden, wenn nach Bereichen oder bestimmten Feldwerten gesucht werden soll (z.B. Firma "*Amazon*" und Datum "%DY%").
+Es kann je Feld eine Suchbedingung bzw. Suchtext eingegeben werden.
+Es wird nur in den angegebenen Feldern gesucht.
+Dokumentation für Suchbedingung / Suchfilter im Parameter value:
+Suchfelder und Suchwerte (flache key-value-pair Liste). Die Datensätze werden danach gefiltert.
+Der Feld-Suchtext bzw. Suchbedingung greift nur für die hier angegebenen Felder.
+Die Suchoperatoren müssen ohne Leerzeichen verkettet werden, also ohne Leerzeichen direkt an die Suchbegriffe angehängt werden (bzw. für NOT-Operator vorangestellt werden).
+Suchoperatoren:
+- * für gefüllte Felder
+- *TEXT* für enthält Feldwert TEXT bzw. trunktierte Suche
+- & als logischer AND Operator
+- "|" (Pippe) als logischer OR Operator
+- ! als logischer NOT Operator als Prefix, muss dem Suchbegriff vorangestellt werden.
+- !* für leere Felder
+- <-> für Datumsbereich, Zeitraum, Bereichssuche, Zahlenbereich; A<->B von A bis einschließlich B; Format für Datumsbereich: DD.MM.YYYY<->DD.MM.YYYY z.B. 01.07.2024<->31.07.2024.
+Beispiele für Suchoperatoren:
+- *TEXT* für trunkierte/Substring Suche nach TEXT (Feldwert enthält TEXT), MUSS zwingend bei unklaren/ungenauen/unspezifischen Eingaben verwendet werden!
+- !*TEXT* für Feldwert enthält TEXT nicht
+- !* für leeren, nicht gefüllte Feldwerte
+- !TEXT für alle Feldwerte, abgesehen von TEXT bzw. alles bis auf TEXT.
+- !A&B für exakte Suche nach B jedoch ohne A
+- "A|B" (Pippe) für exakte Suche nach A oder B
+- !*A*&*B* für Suche nach enthält (Substring) B aber enthält kein A
+- 01.01.2020<->31.12.2020 für Datumssuchbereichs-Suche (Bereichssuche) vom 01.01.2020 bis einschließlich 31.12.2020 (1 Jahr)
+- 01.07.2024<->31.07.2024 für Datumssuchbereichs-Suche (Bereichssuche) vom 01.07.2024 bis einschließlich 31.07.2024 für den Monat Juli 2024 (1 Monat)
+Datumsformat: DD.MM.YYYY
+Zahlenformat: 0.00
+Variablen:
+- %DY% Variable für Datumsbereich im aktuellen/diesen Jahr
+- %DMY% Variable für Datumsbereich im aktuellen/diesen Monat
+- %DWY% Variable für Datumsbereich in der aktuellen/diesen Woche (7 Tage)
+- %B% Variable für angemeldeten Benutzer
+- %D% Variable für aktuelles Datum (heutiger Tag)
+- %D-1% Variable für gestriges Datum bzw. gestern
+- %D-2% Variable für vorgestern
+- %D+1% Variable für morgiges Datum bzw. morgen
+- %D+2% Variable für übermorgen
+Beispiel: Filter für alle Eingangsrechnungen im Zeitraum Juli 2024 (01.07.2024 bis einschließlich 31.07.2024) von Firma Amazon:
+{ date: "01.07.2024<->31.07.2024", c_company: "*Amazon*", inout: "0", type: "Rechnung" }
+    `,
+    parameters: {
+      type: "object",
+      properties: {
+        archive: { type: "string", description: "Name des Archivs" },
+        searchValues: {
+          type: "object",
+          description: "Key-Value Paare für die Feldsuche. Der Key muss Exakt einem Dr.DOC Feldnamen entsprechen (durch das Tool 'drdoc_properties_fields'). Unterstützt Operatoren wie *TEXT*, !*, A<->B",
+        },
+        selection: { type: "string", description: "Mit Semikolon getrennte Liste auszugebender Felder" },
+        count: { type: "number", description: "Maximale Trefferanzahl" },
+      },
+      required: ["archive", "searchValues"],
+    },
+    execute: async (toolCallId: string, args?: { archive?: string; searchValues?: Record<string, any>; selection?: string; count?: number }) => {
+      if (process.env.DRDOC_DEBUG)
+        msgLog('drdoc_search_fields:', args);
+      return safeExecuteClient(["archive", "searchValues"], args, async (client, safeArgs) => {
+        return await client.searchFields(safeArgs.archive, safeArgs.searchValues, {
+          selection: safeArgs.selection,
+          count: safeArgs.count,
+        });
+      });
+    },
+  },
+  {
+    name: "drdoc_search_fulltext",
+    description: `Führt eine Volltextsuche (Text Retrieval, Freitextsuche, Volltextsuche, Text Retrieval, Full-Text-Search) über alle Felder und Metadaten eines Dr.DOC Archivs durch.
+Die Bedeutung der Felder erhältst Du durch das Tool 'drdoc_properties_fields'.
+
+Diese Suche sollte verwendet werden, wenn im Dokumenttext bzw. allen Feldwerten gesucht werden soll, unabhängig davon wo der Text im Dr.DOC Archiv zu finden ist.
+Es muss eine Suchbedingung bzw. Suchtext eingegeben werden, ohne Feldname.
+Es wird eine Suchergebnisliste von vorgefilterten Datensätzen zurückgegeben.
+Suchtext (bzw. Suchbedingung). Die zurückgegebenen Datensätze werden nach diesem Suchtext gefiltert.
+Es soll der Suchtext ohne Feldname angegeben werden. " +Der Suchtext greift für alle Dr.DOC Felder (Volltextsuche), also unabhängig in welchem Feld der Text gefunden wird.
+Die Suchoperatoren müssen ohne Leerzeichen verkettet werden, also ohne Leerzeichen direkt an die Suchbegriffe angehängt werden (bzw. für NOT Operator vorangestellt werden).
+Suchoperatoren:
+- & als logischer AND Operator
+- "|" (Pipe) als logischer OR Operator
+- ! als logischer NOT Operator als Prefix, muss dem Suchbegriff vorangestellt werden.
+Beispiele für Suchoperatoren:
+- !A&B für Suche nach B jedoch ohne A
+- "A|B" für Suche nach A oder B
+Datumsformat: DD.MM.YYYY
+`,
+    parameters: {
+      type: "object",
+      properties: {
+        archive: { type: "string", description: "Name des Archivs" },
+        queryText: { type: "string", description: "Suchtext oder Suchbedingung" },
+        selection: { type: "string", description: "Mit Semikolon getrennte Liste auszugebender Felder" },
+        count: { type: "number", description: "Maximale Trefferanzahl" },
+      },
+      required: ["archive", "queryText"],
+    },
+    execute: async (toolCallId: string, args?: { archive?: string; queryText?: string; selection?: string; count?: number }) => {
+      if (process.env.DRDOC_DEBUG)
+        msgLog('drdoc_search_fulltext:', args);
+      return safeExecuteClient(["archive", "queryText"], args, async (client, safeArgs) => {
+        return await client.textRetrieval(safeArgs.archive, safeArgs.queryText, {
+          selection: safeArgs.selection,
+          count: safeArgs.count,
+        });
+      });
+    },
+  },
+  {
+    name: "drdoc_get_record",
+    description: "Liest einen konkreten Meta-Datensatz anhand seiner ID aus. Die Bedeutung der Felder erhältst Du durch das Tool 'drdoc_properties_fields'.",
+    parameters: {
+      type: "object",
+      properties: {
+        archive: { type: "string", description: "Name des Dr.DOC Archivs" },
+        id: { type: "string", description: "Datensatz-ID (DrDocGUID oder Dokument-Nr.)" },
+        idField: { type: "string", description: "Optionaler Feldname für die ID" },
+      },
+      required: ["archive", "id"],
+    },
+    execute: async (toolCallId: string, args?: { archive?: string; id?: string; idField?: string }) => {
+      return safeExecuteClient(["archive", "id"], args, async (client, safeArgs) => {
+        return await client.getRecord(safeArgs.archive, safeArgs.id, safeArgs.idField);
+      });
+    },
+  },
+  {
+    name: "drdoc_create_record",
+    description: "Erstellt einen neuen Meta-Datensatz in einem Dr.DOC Archiv. Die Bedeutung der Felder erhältst Du durch das Tool 'drdoc_properties_fields'.",
+    parameters: {
+      type: "object",
+      properties: {
+        archive: { type: "string", description: "Name des Dr.DOC Ziel-Archivs" },
+        value: { type: "object", description: "JSON-Objekt mit den Feldinhalten" },
+      },
+      required: ["archive", "value"],
+    },
+    execute: async (toolCallId: string, args?: { archive?: string; value?: Record<string, any> }) => {
+      return safeExecuteClient(["archive", "value"], args, async (client, safeArgs) => {
+        return await client.createRecord(safeArgs.archive, safeArgs.value);
+      });
+    },
+  },
+  /*{
+    name: "drdoc_get_document",
+    description: "Liest ein Dokumenteninhalt (Blob) anhand seiner ID aus.",
+    parameters: {
+      type: "object",
+      properties: {
+        archive: { type: "string", description: "Name des Dr.DOC Archivs" },
+        id: { type: "string", description: "Datensatz-ID (DrDocGUID oder Dokument-Nr.)" },
+        idField: { type: "string", description: "Optionaler Feldname für die ID" },
+      },
+      required: ["archive", "id"],
+    },
+    execute: async (toolCallId: string, args?: { archive?: string; id?: string; idField?: string }) => {
+      return safeExecuteClient(["archive", "id"], args, async (client, safeArgs) => {
+        return await client.getDocument(safeArgs.archive, safeArgs.id, safeArgs.idField);
+      });
+    },
+  },*/
+
+  {
+    name: "drdoc_get_document",
+    description: "Liest den Dokumenteninhalt (Blob) anhand der ID aus, speichert die Datei lokal und bereitet sie für die Anzeige im Pi Agent auf.",
+    parameters: {
+      type: "object",
+      properties: {
+        archive: { type: "string", description: "Name des Dr.DOC Archivs" },
+        id: { type: "string", description: "Datensatz-ID (DrDocGUID oder Dokument-Nr.)" },
+        idField: { type: "string", description: "Optionaler Feldname für die ID" },
+      },
+      required: ["archive", "id"],
+    },
+    execute: async (toolCallId: string, args?: { archive?: string; id?: string; idField?: string }) => {
+      return safeExecuteClient(["archive", "id"], args, async (client, safeArgs) => {
+        // Dokumenten-Blob vom Client abrufen
+        const responseData = await client.getDocument(safeArgs.archive, safeArgs.id, safeArgs.idField);
+
+        // Konvertierung in Node.js Buffer und Ermittlung des MIME-Typs
+        let buffer: Buffer;
+        let mimeType = "application/octet-stream";
+
+        if (typeof Blob !== "undefined" && responseData instanceof Blob) {
+          mimeType = responseData.type || mimeType;
+          const arrayBuffer = await responseData.arrayBuffer();
+          buffer = Buffer.from(arrayBuffer);
+        } else if (Buffer.isBuffer(responseData)) {
+          buffer = responseData;
+        } else {
+          buffer = Buffer.from(responseData as any);
+        }
+
+        // Download-Ordner im Arbeitsverzeichnis sicherstellen
+        //const downloadsDir = path.join(process.cwd());
+
+        // const downloadsDir = path.join(process.cwd(), "downloads");
+
+        // Bestimmung des Zielverzeichnisses über das Home-Verzeichnis
+        const downloadsDir = process.env.DRDOC_DOWNLOAD_DIR || path.join(os.homedir(), "downloads", "drdoc"); //, "downloads");
+
+        // 1. Umgebungsvariable, 2. Client-Config, 3. Home-Verzeichnis
+        //const downloadsDir = process.env.DRDOC_DOWNLOAD_DIR
+        //  || client.getConfig?.()?.downloadDir
+        //  || path.join(os.homedir(), "Downloads");
+
+        // Alternativ im temporären Verzeichnis des Betriebssystems:
+        //const downloadsDir = process.env.DRDOC_DOWNLOAD_DIR || path.join(os.tmpdir(), "drdoc-downloads");
+
+        if (!fs.existsSync(downloadsDir)) {
+          fs.mkdirSync(downloadsDir, { recursive: true });
+        }
+
+        // Dateiendung bestimmen und Dateinamen generieren
+        const extension = mimeType.includes("/") ? mimeType.split("/")[1] : "bin";
+        const safeId = safeArgs.id.replace(/[^a-zA-Z0-9_-]/g, "_");
+        const fileName = `${safeArgs.archive}_${safeId}.${extension}`;
+        const filePath = path.join(downloadsDir, fileName);
+
+        // Datei im Dateisystem ablegen
+        fs.writeFileSync(filePath, buffer);
+
+        // Web-URL für den direkten Aufruf im Browser erzeugen
+        const baseUrl = client.getConfig?.()?.baseUrl || "https://drdoc.com";
+        const webUrl = new URL("/model/document", baseUrl);
+        webUrl.searchParams.set("action", "get");
+        webUrl.searchParams.set("archive", safeArgs.archive);
+        webUrl.searchParams.set("id", safeArgs.id);
+        if (safeArgs.idField) {
+          webUrl.searchParams.set("id_field", safeArgs.idField);
+        }
+        webUrl.searchParams.set("download", "false");
+
+        // Rückgabe-Objekt für die Darstellung im Pi Agent
+        const result: Record<string, any> = {
+          message: `Dokument wurde erfolgreich heruntergeladen und lokal gespeichert nach "${filePath}".`,
+          filePath: filePath,
+          fileName: fileName,
+          webUrl: webUrl.toString(),
+          mimeType: mimeType,
+          sizeBytes: buffer.length,
+        };
+
+        // Bei Bildern wird eine Base64-Data-URL zur direkten Inline-Anzeige hinzugefügt
+        if (mimeType.startsWith("image/")) {
+          result.imageBase64 = `data:${mimeType};base64,${buffer.toString("base64")}`;
+        }
+
+        return result;
+      });
+    },
+  },
+];

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "CommonJS",
+        "declaration": true,
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "include": [
+        "src/**/*"
+    ]
+}