@gandalan/weblibs 1.5.17 → 1.5.19

package/README.md

@@ -1,35 +1,124 @@
 # WebLibs for Gandalan JS/TS projects
 
-## Initialize Fluent IDAS API + local API
+## Deutsch
 
-Example:
+### Zweck
+`@gandalan/weblibs` stellt Hilfsfunktionen für die Authentifizierung und API-Kommunikation mit IDAS sowie lokale API-Aufrufe bereit.
 
+### Referenz
+- IDAS API (Swagger): https://api.dev.idas-cloudservices.net/swagger/
+
+### Voraussetzungen
+- Browser-Umgebung (es werden `window`, `localStorage`, URL-Redirects und `fetch` verwendet)
+- Gültiger App-Token als UUID (wird auf Anfrage von Gandalan ausgegeben)
+- Kontakt für Zugangsdaten/App-Token: dev-support@gandalan.de
+- IDAS/Auth-Base-URL vorzugsweise aus `fetchEnvConfig(...)` (z. B. `envConfig.idas`)
+- Falls die URL manuell gesetzt wird: mit abschließendem Slash (z. B. `https://api.dev.idas-cloudservices.net/api/`)
+
+### Installation
+```bash
+npm i @gandalan/weblibs
+```
+
+### Schnellstart (Fluent API + Auth)
 ```js
 import { fetchEnvConfig, fluentApi, fluentIdasAuthManager } from '@gandalan/weblibs';
 
 async function initializeAuthAndApi() {
-    const serviceName = 'myService'
-    const appToken = 'your-app-token';
-    const envConfig = await fetchEnvConfig('dev'); // Replace 'dev' with your desired environment
+    const serviceName = 'myService';
+    const appToken = '00000000-0000-0000-0000-000000000000'; // UUID
+    const envConfig = await fetchEnvConfig('dev'); // envConfig.idas kommt aus fetchEnvConfig(...)
 
-    const authManager = await fluentIdasAuthManager(appToken, envConfig.idas).init();
-    if (!authManager) {
-        return; // init() has redirected to login.
+    let authManager;
+    try {
+        authManager = await fluentIdasAuthManager(appToken, envConfig.idas).init();
+    } catch {
+        // init() kann auf Login umleiten und dabei eine Exception werfen.
+        // In diesem Fall Seite verlassen / später erneut starten.
+        return;
     }
 
-    globalThis.idas = fluentApi(envConfig.idas, authManager, serviceName);   // IDAS-API instance
-    globalThis.api = fluentApi("/api/", authManager, serviceName);           // Local API instance
+    const idas = fluentApi(envConfig.idas, authManager, serviceName);
+    const api = fluentApi('/api/', authManager, serviceName);
+
+    const mandanten = await idas.get('mandanten');
+    console.log(mandanten[0]?.Name);
+
+    const localResult = await api.get('some-endpoint');
+    console.log(localResult);
 }
 ```
 
-## Usage samples
+### Exportierte APIs (Kurzüberblick)
+- `fetchEnvConfig(env)` lädt Endpunktkonfiguration (z. B. `dev`, `staging`, `produktiv`)
+- `fluentIdasAuthManager(appToken, authBaseUrl)` erzeugt Auth-Manager
+- `fluentApi(baseUrl, authManager, serviceName)` erzeugt API-Client mit `get/put/post/delete`
+- `createAuthManager()`, `createApi()`, `restClient()` für manuelle Konfiguration
+- Legacy zusätzlich vorhanden: `initIDAS`, `IDASFactory`, `RESTClient`
+
+### Wichtige Hinweise
+- `init()` gibt nicht immer nur `null` zurück, sondern kann beim Redirect eine Exception auslösen.
+- Refresh-Token wird aus URL-Parameter `t` gelesen und in `localStorage` (`idas-refresh-token`) persistiert.
+- Ohne gültigen Auth-Status werden Requests ggf. intern per `ensureAuthenticated()` nachgezogen.
+
+---
+
+## English
+
+### Purpose
+`@gandalan/weblibs` provides helpers for authentication and API communication with IDAS as well as local API calls.
+
+### Reference
+- IDAS API (Swagger): https://api.dev.idas-cloudservices.net/swagger/
+
+### Requirements
+- Browser environment (uses `window`, `localStorage`, URL redirects, and `fetch`)
+- Valid app token in UUID format (issued by Gandalan on request)
+- Contact for credentials/app token: dev-support@gandalan.de
+- Prefer the IDAS/auth base URL from `fetchEnvConfig(...)` (for example `envConfig.idas`)
+- If the URL is set manually, use a trailing slash (for example `https://api.dev.idas-cloudservices.net/api/`)
 
+### Installation
+```bash
+npm i @gandalan/weblibs
+```
+
+### Quick start (Fluent API + auth)
 ```js
-// Example IDAS API usage
-const responseIdas = await globalThis.idas.get('mandanten');
-console.log(responseIdas[0].Name);
+import { fetchEnvConfig, fluentApi, fluentIdasAuthManager } from '@gandalan/weblibs';
+
+async function initializeAuthAndApi() {
+    const serviceName = 'myService';
+    const appToken = '00000000-0000-0000-0000-000000000000'; // UUID
+    const envConfig = await fetchEnvConfig('dev'); // envConfig.idas is provided by fetchEnvConfig(...)
+
+    let authManager;
+    try {
+        authManager = await fluentIdasAuthManager(appToken, envConfig.idas).init();
+    } catch {
+        // init() may redirect to login and throw while doing so.
+        return;
+    }
+
+    const idas = fluentApi(envConfig.idas, authManager, serviceName);
+    const api = fluentApi('/api/', authManager, serviceName);
+
+    const mandanten = await idas.get('mandanten');
+    console.log(mandanten[0]?.Name);
 
-// Example local API usage
-const responseApi = await globalThis.api.get('some-endpoint');
-console.log(responseApi);
+    const localResult = await api.get('some-endpoint');
+    console.log(localResult);
+}
 ```
+
+### Exported APIs (short overview)
+- `fetchEnvConfig(env)` loads endpoint configuration (for example `dev`, `staging`, `produktiv`)
+- `fluentIdasAuthManager(appToken, authBaseUrl)` creates an auth manager
+- `fluentApi(baseUrl, authManager, serviceName)` creates an API client with `get/put/post/delete`
+- `createAuthManager()`, `createApi()`, `restClient()` for manual composition
+- Legacy exports still available: `initIDAS`, `IDASFactory`, `RESTClient`
+
+### Important notes
+- `init()` does not only return `null`; it may throw during login redirect.
+- Refresh token can be read from URL parameter `t` and is stored in `localStorage` (`idas-refresh-token`).
+- Without valid auth state, requests may trigger `ensureAuthenticated()` internally.

package/api/business/ablageApi.js

@@ -0,0 +1,106 @@
+/**
+ * @typedef {import('../fluentApi.js').FluentApi} FluentApi
+ * @typedef {import('../dtos/produktion.js').AblageDTO} AblageDTO
+ * @typedef {import('../dtos/produktion.js').AblageFachDTO} AblageFachDTO
+ * @typedef {import('../dtos/produktion.js').FachzuordnungResultDTO} FachzuordnungResultDTO
+ */
+
+/**
+ * Ablage API - Storage and bin management
+ * @param {FluentApi} fluentApi
+ */
+export function createAblageApi(fluentApi) {
+    return {
+        // AblageWebRoutinen
+        /**
+         * Get storage by GUID
+         * @param {string} guid
+         * @returns {Promise<AblageDTO>}
+         */
+        get: (guid) => fluentApi.get(`Ablage/?id=${guid}`),
+
+        /**
+         * Get all storage locations
+         * @param {Date} [changedSince]
+         * @param {boolean} [includeDetails=true]
+         * @returns {Promise<AblageDTO[]>}
+         */
+        getAll: (changedSince, includeDetails = true) => {
+            if (changedSince) {
+                return fluentApi.get(`Ablage?changedSince=${changedSince.toISOString()}&includeDetails=${includeDetails}`);
+            }
+            return fluentApi.get(`Ablage?includeDetails=${includeDetails}`);
+        },
+
+        /**
+         * Save storage
+         * @param {AblageDTO} dto
+         * @returns {Promise<void>}
+         */
+        save: (dto) => fluentApi.put("Ablage/", dto),
+
+        /**
+         * Delete storage
+         * @param {string} guid
+         * @returns {Promise<void>}
+         */
+        delete: (guid) => fluentApi.delete(`Ablage/?id=${guid}`),
+
+        /**
+         * Distribute serie to bins
+         * @param {string} serieGuid
+         * @returns {Promise<FachzuordnungResultDTO>}
+         */
+        serienFachverteilung: (serieGuid) =>
+            fluentApi.put(`Ablage/SerienFachverteilung/${serieGuid}`, null),
+
+        /**
+         * Distribute AV positions to bins
+         * @param {string[]} avGuids
+         * @returns {Promise<FachzuordnungResultDTO>}
+         */
+        fachverteilung: (avGuids) =>
+            fluentApi.put("Ablage/Fachverteilung", avGuids),
+
+        // AblageFachWebRoutinen
+        fach: {
+            /**
+             * Get bin by GUID
+             * @param {string} guid
+             * @returns {Promise<AblageFachDTO>}
+             */
+            get: (guid) => fluentApi.get(`AblageFach/?id=${guid}`),
+
+            /**
+             * Get all bins
+             * @param {Date} [changedSince]
+             * @param {boolean} [includeDetails=true]
+             * @returns {Promise<AblageFachDTO[]>}
+             */
+            getAll: (changedSince, includeDetails = true) => {
+                if (changedSince) {
+                    return fluentApi.get(`AblageFach?changedSince=${changedSince.toISOString()}&includeDetails=${includeDetails}`);
+                }
+                return fluentApi.get(`AblageFach?includeDetails=${includeDetails}`);
+            },
+
+            /**
+             * Save bin
+             * @param {AblageFachDTO} dto
+             * @returns {Promise<void>}
+             */
+            save: (dto) => fluentApi.put("AblageFach/", dto),
+
+            /**
+             * Delete bin
+             * @param {string} guid
+             * @returns {Promise<void>}
+             */
+            delete: (guid) => fluentApi.delete(`AblageFach/?id=${guid}`),
+        },
+    };
+}
+
+/**
+ * @typedef {ReturnType<typeof createAblageApi>} AblageApi
+ */

package/api/business/anpassungApi.js

@@ -0,0 +1,74 @@
+/**
+ * @typedef {import('../fluentApi.js').FluentApi} FluentApi
+ * @typedef {import('../dtos/index.js').AnpassungDTO} AnpassungDTO
+ * @typedef {import('../dtos/index.js').AnpassungVorlageDTO} AnpassungVorlageDTO
+ */
+
+/**
+ * Anpassung API - Customization and adjustment management
+ * @param {FluentApi} fluentApi
+ */
+export function createAnpassungApi(fluentApi) {
+    return {
+        // AnpassungenWebRoutinen
+        /**
+         * Get all adjustments
+         * @returns {Promise<AnpassungDTO[]>}
+         */
+        getAll: () => fluentApi.get("Anpassungen"),
+
+        /**
+         * Save adjustment
+         * @param {AnpassungDTO} dto
+         * @returns {Promise<void>}
+         */
+        save: (dto) => fluentApi.put(`Anpassungen/${dto.anpassungGuid}`, dto),
+
+        /**
+         * Delete adjustment
+         * @param {string} anpassungGuid
+         * @returns {Promise<void>}
+         */
+        delete: (anpassungGuid) => fluentApi.delete(`Anpassungen/${anpassungGuid}`),
+
+        /**
+         * Run adjustment web job
+         * @returns {Promise<void>}
+         */
+        runWebJob: () => fluentApi.post("Anpassungen/WebJob", ""),
+
+        // AnpassungVorlagenWebRoutinen
+        vorlage: {
+            /**
+             * Get all adjustment templates
+             * @returns {Promise<AnpassungVorlageDTO[]>}
+             */
+            getAll: () => fluentApi.get("AnpassungVorlagen"),
+
+            /**
+             * Get adjustment template by GUID
+             * @param {string} guid
+             * @returns {Promise<AnpassungVorlageDTO>}
+             */
+            get: (guid) => fluentApi.get(`AnpassungVorlagen/${guid}`),
+
+            /**
+             * Save adjustment template
+             * @param {AnpassungVorlageDTO} dto
+             * @returns {Promise<void>}
+             */
+            save: (dto) => fluentApi.put(`AnpassungVorlagen/${dto.anpassungVorlageGuid}`, dto),
+
+            /**
+             * Delete adjustment template
+             * @param {string} guid
+             * @returns {Promise<void>}
+             */
+            delete: (guid) => fluentApi.delete(`AnpassungVorlagen/${guid}`),
+        },
+    };
+}
+
+/**
+ * @typedef {ReturnType<typeof createAnpassungApi>} AnpassungApi
+ */

package/api/business/artikelApi.js

@@ -0,0 +1,242 @@
+/**
+ * @typedef {import('../fluentApi.js').FluentApi} FluentApi
+ * @typedef {import('../dtos/index.js').WarenGruppeDTO} WarenGruppeDTO
+ * @typedef {import('../dtos/index.js').KatalogArtikelDTO} KatalogArtikelDTO
+ * @typedef {import('../dtos/index.js').ProduktGruppeDTO} ProduktGruppeDTO
+ * @typedef {import('../dtos/index.js').ProduktFamilieDTO} ProduktFamilieDTO
+ * @typedef {import('../dtos/index.js').KomponenteDTO} KomponenteDTO
+ * @typedef {import('../dtos/index.js').VarianteDTO} VarianteDTO
+ * @typedef {import('../dtos/index.js').KonturDTO} KonturDTO
+ * @typedef {import('../dtos/index.js').KatalogArtikelIndiDatenDTO} KatalogArtikelIndiDatenDTO
+ * @typedef {import('../dtos/index.js').SchnittDTO} SchnittDTO
+ * @typedef {import('../dtos/belege.js').BelegDTO} BelegDTO
+ */
+
+/**
+ * Artikel API - Article and product management
+ * @param {FluentApi} fluentApi
+ */
+export function createArtikelApi(fluentApi) {
+    return {
+    // ArtikelWebRoutinen
+    /**
+     * Get all articles
+     * @param {Date} [changedSince] - Filter by change date
+     * @returns {Promise<WarenGruppeDTO[]>}
+     */
+        getAll: (changedSince) => {
+            const url = changedSince
+                ? `Artikel?changedSince=${changedSince.toISOString()}`
+                : "Artikel";
+            return fluentApi.get(url);
+        },
+
+        /**
+     * Save article
+     * @param {KatalogArtikelDTO} artikel
+     * @returns {Promise<KatalogArtikelDTO>}
+     */
+        saveArtikel: (artikel) => fluentApi.put(`Artikel/${artikel.katalogArtikelGuid}`, artikel),
+
+        /**
+     * Delete article
+     * @param {KatalogArtikelDTO} artikel
+     * @returns {Promise<void>}
+     */
+        deleteArtikel: (artikel) => fluentApi.delete(`Artikel/${artikel.katalogArtikelGuid}`),
+
+        // ArtikelIndiDatenWebRoutinen
+        /**
+     * Get all article individual data
+     * @param {Date} [changedSince] - Filter by change date
+     * @returns {Promise<KatalogArtikelIndiDatenDTO[]>}
+     */
+        getAllIndiDaten: (changedSince) => {
+            const url = changedSince
+                ? `ArtikelIndiDaten?changedSince=${changedSince.toISOString()}`
+                : "ArtikelIndiDaten";
+            return fluentApi.get(url);
+        },
+
+        /**
+     * Save article individual data
+     * @param {KatalogArtikelIndiDatenDTO} daten
+     * @returns {Promise<void>}
+     */
+        saveArtikelIndiDaten: (daten) => fluentApi.put(`ArtikelIndiDaten/${daten.katalogArtikelGuid}`, daten),
+
+        /**
+     * Delete article individual data
+     * @param {KatalogArtikelIndiDatenDTO} daten
+     * @returns {Promise<void>}
+     */
+        deleteArtikelIndiDaten: (daten) => fluentApi.delete(`ArtikelIndiDaten/${daten.katalogArtikelGuid}`),
+
+        // WarenGruppeWebRoutinen
+        /**
+     * Get all product groups
+     * @returns {Promise<WarenGruppeDTO[]>}
+     */
+        getAllWarenGruppen: () => fluentApi.get("WarenGruppe"),
+
+        /**
+     * Save product group
+     * @param {WarenGruppeDTO} dto
+     * @returns {Promise<void>}
+     */
+        saveWarenGruppe: (dto) => fluentApi.put(`WarenGruppe/${dto.warenGruppeGuid}`, dto),
+
+        // ProduktGruppenWebRoutinen
+        /**
+     * Get all product groups
+     * @param {boolean} [includeFamilien=true] - Include families and variants
+     * @returns {Promise<ProduktGruppeDTO[]>}
+     */
+        getAllProduktGruppen: (includeFamilien = true) =>
+            fluentApi.get(`ProduktGruppe?includeFamilien=${includeFamilien}&includeVarianten=${includeFamilien}&includeUIDefs=${includeFamilien}&maxLevel=99`),
+
+        /**
+     * Save product group
+     * @param {ProduktGruppeDTO} produktGruppe
+     * @returns {Promise<ProduktGruppeDTO>}
+     */
+        saveProduktGruppe: (produktGruppe) =>
+            fluentApi.put(`ProduktGruppe/${produktGruppe.produktGruppeGuid}`, produktGruppe),
+
+        // ProduktFamilienWebRoutinen
+        /**
+     * Get all product families
+     * @param {boolean} [includeVarianten=true] - Include variants
+     * @returns {Promise<ProduktFamilieDTO[]>}
+     */
+        getAllProduktFamilien: (includeVarianten = true) =>
+            fluentApi.get(`ProduktFamilie?includeVarianten=${includeVarianten}&includeUIDefs=${includeVarianten}&maxLevel=99`),
+
+        /**
+     * Save product family
+     * @param {ProduktFamilieDTO} produktFamilie
+     * @returns {Promise<ProduktFamilieDTO>}
+     */
+        saveProduktFamilie: (produktFamilie) =>
+            fluentApi.put(`ProduktFamilie/${produktFamilie.produktFamilieGuid}`, produktFamilie),
+
+        // KomponentenWebRoutinen
+        /**
+     * Get all components
+     * @returns {Promise<KomponenteDTO[]>}
+     */
+        getAllKomponenten: () => fluentApi.get("Komponente"),
+
+        /**
+     * Save component
+     * @param {KomponenteDTO} dto
+     * @returns {Promise<void>}
+     */
+        saveKomponente: (dto) => fluentApi.put("Komponente", dto),
+
+        // VariantenWebRoutinen
+        /**
+     * Get all variants
+     * @returns {Promise<VarianteDTO[]>}
+     */
+        getAllVarianten: () => fluentApi.get("Variante?includeUIDefs=true&maxLevel=99"),
+
+        /**
+     * Get all variant GUIDs
+     * @returns {Promise<string[]>}
+     */
+        getAllVariantenGuids: () => fluentApi.get("Variante/GetAllGuids"),
+
+        /**
+     * Get all variant changes since date
+     * @param {Date} [changedSince]
+     * @returns {Promise<string[]>}
+     */
+        getAllVariantenChanges: (changedSince) => {
+            const url = changedSince
+                ? `Variante/GetAllVariantenChanges?changedSince=${changedSince.toISOString()}`
+                : "Variante/GetAllGuids";
+            return fluentApi.get(url);
+        },
+
+        /**
+     * Get variant by GUID
+     * @param {string} varianteGuid
+     * @param {boolean} [includeUIDefs=true]
+     * @param {boolean} [includeKonfigs=true]
+     * @returns {Promise<VarianteDTO>}
+     */
+        getVariante: (varianteGuid, includeUIDefs = true, includeKonfigs = true) =>
+            fluentApi.get(`Variante/${varianteGuid}?includeUIDefs=${includeUIDefs}&maxLevel=99&includeKonfigs=${includeKonfigs}`),
+
+        /**
+     * Save variant
+     * @param {VarianteDTO} variante
+     * @returns {Promise<VarianteDTO>}
+     */
+        saveVariante: (variante) => fluentApi.put(`Variante/${variante.varianteGuid}`, variante),
+
+        /**
+     * Trigger variant cache web job
+     * @returns {Promise<void>}
+     */
+        cacheWebJob: () => fluentApi.post("Variante/CacheWebJob", null),
+
+        // KonturenWebRoutinen
+        /**
+     * Get all contours
+     * @returns {Promise<KonturDTO[]>}
+     */
+        getAllKonturen: () => fluentApi.get("Kontur"),
+
+        /**
+     * Save contour
+     * @param {KonturDTO} dto
+     * @returns {Promise<void>}
+     */
+        saveKontur: (dto) => fluentApi.put("Kontur", dto),
+
+        // SchnitteWebRoutinen
+        /**
+     * Get all cuts
+     * @returns {Promise<SchnittDTO[]>}
+     */
+        getAllSchnitte: () => fluentApi.get("Schnitt"),
+
+        /**
+     * Save cut
+     * @param {SchnittDTO} dto
+     * @returns {Promise<void>}
+     */
+        saveSchnitt: (dto) => fluentApi.put("Schnitt", dto),
+
+        // SonderfarbWebRoutinen
+        /**
+     * Calculate special colors for beleg
+     * @param {string} belegGuid
+      * @returns {Promise<BelegDTO>}
+     */
+        berechneSonderfarben: (belegGuid) => fluentApi.post(`BelegSonderfarben?bguid=${belegGuid}`, null),
+
+        // BenutzerVariantenWebRoutinen
+        /**
+     * Get user variants
+     * @param {string} benutzerGuid
+     * @param {boolean} mitSperrliste
+     * @returns {Promise<VarianteDTO[]>}
+     */
+        getBenutzerVarianten: (benutzerGuid, mitSperrliste) =>
+            fluentApi.get(`BenutzerVarianten?id=${benutzerGuid}&mitSperrliste=${mitSperrliste}`),
+
+        // ResetCacheVariantenListenWebRoutinen
+        /**
+     * Reset variant list cache
+     * @returns {Promise<void>}
+     */
+        resetCacheVariantenListen: () => fluentApi.put("ResetCacheVariantenListen", null),
+    };
+}
+
+/**
+   * @typedef {ReturnType<typeof createArtikelApi>} ArtikelApi
+   */

package/api/business/authApi.js

@@ -0,0 +1,63 @@
+/**
+ * @typedef {import('../fluentApi.js').FluentApi} FluentApi
+ * @typedef {import('../dtos/index.js').LoginDTO} LoginDTO
+ * @typedef {import('../dtos/index.js').CreateServiceTokenRequestDTO} CreateServiceTokenRequestDTO
+ */
+
+/**
+ * Auth API - Authentication and token management
+ * @param {FluentApi} fluentApi
+ */
+export function createAuthApi(fluentApi) {
+    return {
+        // LoginJwtRoutinen
+        /**
+         * Authenticate
+         * @param {LoginDTO} dto
+         * @returns {Promise<string>}
+         */
+        authenticate: (dto) => fluentApi.post("LoginJwt/Authenticate", dto),
+
+        /**
+         * Authenticate for function
+         * @param {string} email
+         * @returns {Promise<string>}
+         */
+        authenticateForFunction: (email) =>
+            fluentApi.post(`LoginJwt/AuthenticateForFunction/?email=${encodeURIComponent(email)}`, null),
+
+        /**
+         * Refresh token
+         * @param {string} token
+         * @returns {Promise<string>}
+         */
+        refreshToken: (token) => fluentApi.put("LoginJwt/Refresh", token),
+
+        /**
+         * Create service token
+         * @param {CreateServiceTokenRequestDTO} [dto]
+         * @returns {Promise<string>}
+         */
+        createServiceToken: (dto) => fluentApi.post("LoginJwt/CreateServiceToken", dto),
+
+        // AuthTokenWebRoutinen
+        /**
+         * Remove expired tokens
+         * @returns {Promise<void>}
+         */
+        removeExpiredTokens: () =>
+            fluentApi.post("AuthToken/RemoveExpiredTokens", null),
+
+        /**
+         * Get external app auth token
+         * @param {string} fremdApp
+         * @returns {Promise<import('../dtos/index.js').UserAuthTokenDTO>}
+         */
+        getFremdAppAuthToken: (fremdApp) =>
+            fluentApi.get(`AuthToken/GetFremdAppAuthToken?fremdApp=${fremdApp}`),
+    };
+}
+
+/**
+ * @typedef {ReturnType<typeof createAuthApi>} AuthApi
+ */